home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1996 #6 / Amiga Plus CD - 1996 - No. 06.iso / pd / programmierung / gadutil / docs / gadutil.doc < prev    next >
Text File  |  1996-05-31  |  89KB  |  2,656 lines
  1. TABLE OF CONTENTS
  2.  
  3. gadutil.library/GU_AddTail
  4. gadutil.library/GU_AttachList
  5. gadutil.library/GU_BeginRefresh
  6. gadutil.library/GU_BlockInput
  7. gadutil.library/GU_ChangeStr
  8. gadutil.library/GU_CheckVersion
  9. gadutil.library/GU_ClearList
  10. gadutil.library/GU_ClearWindow
  11. gadutil.library/GU_CloseCatalog
  12. gadutil.library/GU_CloseFont
  13. gadutil.library/GU_CoordsInGadBox
  14. gadutil.library/GU_CountNodes
  15. gadutil.library/GU_CreateContext
  16. gadutil.library/GU_CreateGadgetA
  17. gadutil.library/GU_CreateLocMenuA
  18. gadutil.library/GU_CreateMenusA
  19. gadutil.library/GU_DetachList
  20. gadutil.library/GU_DisableGadget
  21. gadutil.library/GU_DrawBevelBoxA
  22. gadutil.library/GU_EndRefresh
  23. gadutil.library/GU_FilterIMsg
  24. gadutil.library/GU_FindNode
  25. gadutil.library/GU_FreeGadgets
  26. gadutil.library/GU_FreeInput
  27. gadutil.library/GU_FreeLayoutGadgets
  28. gadutil.library/GU_FreeMenus
  29. gadutil.library/GU_FreeVisualInfo
  30. gadutil.library/GU_GadgetArrayIndex
  31. gadutil.library/GU_GetGadgetAttrsA
  32. gadutil.library/GU_GetGadgetPtr
  33. gadutil.library/GU_GetIMsg
  34. gadutil.library/GU_GetLocaleStr
  35. gadutil.library/GU_GetVisualInfoA
  36. gadutil.library/GU_LayoutGadgetsA
  37. gadutil.library/GU_LayoutMenuItemsA
  38. gadutil.library/GU_LayoutMenusA
  39. gadutil.library/GU_NewList
  40. gadutil.library/GU_NodeDown
  41. gadutil.library/GU_NodeUp
  42. gadutil.library/GU_OpenCatalog
  43. gadutil.library/GU_OpenFont
  44. gadutil.library/GU_PostFilterIMsg
  45. gadutil.library/GU_RefreshBoxes
  46. gadutil.library/GU_RefreshWindow
  47. gadutil.library/GU_ReplyIMsg
  48. gadutil.library/GU_SetGadgetAttrsA
  49. gadutil.library/GU_SetGUGadAttrsA
  50. gadutil.library/GU_SetToggle
  51. gadutil.library/GU_SizeWindow
  52. gadutil.library/GU_SortList
  53. gadutil.library/GU_TextWidth
  54. gadutil.library/GU_UpdateProgress
  55. Œ gadutil.library/GU_AddTail                         gadutil.library/GU_AddTail
  56.  
  57.    NAME
  58.     GU_AddTail -- Add a node to the end of a listview's list.
  59.  
  60.    SYNOPSIS
  61.     node = GU_AddTail(gad, string, list)
  62.     D0, SR (Z)        D0   A0      A1
  63.  
  64.     struct Node *GU_AddTail(struct Gadget *, STRPTR, struct List *);
  65.  
  66.    FUNCTION
  67.     Add a node to the end of a list linked to a gadget (eg. a ListView).
  68.  
  69.     Normally this is used to add a node to a listview list, but it can
  70.     also be used if you eg have another list that that contains
  71.     information about the items in the listview. This list will then
  72.     also be deallocated at the same time as the listview's own list.
  73.     If you do this, be sure to clear the list header of this other list
  74.     when you want to deallocate the list (you can use the GU_NewList
  75.     function).
  76.  
  77.    INPUTS
  78.     gad    - Gadget to keep the nodes in (ie the ListView gadget).
  79.  
  80.     string - String to put in the nodes' LN_NAME field (visible entry).
  81.  
  82.     list   - List to add the node to.
  83.  
  84.    RESULT
  85.     node - Struct Node for success, FALSE for error.
  86.     SR(Z)- 0 for success, 1 for error.
  87.  
  88.    NOTES
  89.     The SR(Z) is probably most usable for assembly programmers.
  90.  
  91.    BUGS
  92.     none known
  93.  
  94.    SEE ALSO
  95.     GU_CountNodes(), GU_NewList(), GU_ClearList(), GU_DetachList(),
  96.     GU_AttachList(), GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_SortList()
  97. gadutil.library/GU_AttachList                   gadutil.library/GU_AttachList
  98.  
  99.    NAME
  100.     GU_AttachList -- Change a listview's current list.
  101.  
  102.    SYNOPSIS
  103.     GU_AttachList(gad, win, list)
  104.                   D0   A0   A1
  105.  
  106.     VOID GU_AttachList(struct Gadget *, struct Window *, struct List *);
  107.  
  108.    FUNCTION
  109.     Attach a new (or changed) list to a listview. The new list will be
  110.     shown immediately.
  111.  
  112.    INPUTS
  113.     gad  - Gadget to change.
  114.     win  - Window that the gadget is located in.
  115.     list - List to connect to the listview gadget.
  116.  
  117.    RESULT
  118.     none
  119.  
  120.    BUGS
  121.     none known
  122.  
  123.    SEE ALSO
  124.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_NewList()
  125.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  126. gadutil.library/GU_BeginRefresh               gadutil.library/GU_BeginRefresh
  127.  
  128.    NAME
  129.     GU_BeginRefresh -- Begin refreshing friendly to GadTools.
  130.  
  131.    SYNOPSIS
  132.     GU_BeginRefresh(win)
  133.                     A0
  134.  
  135.     VOID GU_BeginRefresh(struct Window *);
  136.  
  137.    FUNCTION
  138.  
  139.     Invokes the intuition.library/BeginRefresh() function in a manner
  140.     friendly to the Gadget Toolkit. This function call permits the
  141.     GadTools gadgets to refresh themselves at the correct time.
  142.     Call GU_EndRefresh() function when done.
  143.  
  144.    INPUTS
  145.     win - pointer to Window structure for which a IDCMP_REFRESHWINDOW
  146.           IDCMP event was received.
  147.  
  148.    NOTES
  149.     See gadtools/GT_BeginRefresh() for more information.
  150.  
  151.    SEE ALSO
  152.     GU_EndRefresh(), gadtools/GT_BeginRefresh(), intuition/BeginRefresh()
  153. gadutil.library/GU_BlockInput                   gadutil.library/GU_BlockInput
  154.  
  155.    NAME
  156.     GU_BlockInput -- Block all input to a window.
  157.  
  158.    SYNOPSIS
  159.     GU_BlockInput(window)
  160.                   A0
  161.  
  162.     VOID GU_BlockInput(struct Window *);
  163.  
  164.    FUNCTION
  165.     Changes the window's pointer to the standard wait pointer (OS 2.0)
  166.     or the preferred wait pointer (OS 3.0+) and opens a requester to
  167.     block the user input of the given window. The requester that is
  168.     opened is not visible.
  169.  
  170.    INPUTS
  171.     window - the parent window for the requester. This is the window
  172.          that will be blocked for user input.
  173.  
  174.    EXAMPLE
  175.  
  176.     BlockInput(myWin);
  177.     About();
  178.     FreeInput();
  179.  
  180.     Will block the parent window for user input while displaying the
  181.     About requester of a program.
  182.  
  183.    SEE ALSO
  184.     GU_FreeInput()
  185. gadutil.library/GU_ChangeStr                     gadutil.library/GU_ChangeStr
  186.  
  187.    NAME
  188.     GU_ChangeStr -- Change the contents of string gadget.
  189.  
  190.    SYNOPSIS
  191.     GU_ChangeStr(gad, string, win)
  192.                  D0   A0      A1
  193.  
  194.     VOID GU_ChangeStr(struct Gadget *, struct Window *, STRPTR);
  195.  
  196.    FUNCTION
  197.     Change the string in a string gadget.
  198.  
  199.    INPUTS
  200.     gad    - Gadget to change
  201.     string - New string
  202.     win    - Window that the gadget is located in.
  203.  
  204.    RESULT
  205.     none
  206.  
  207.    BUGS
  208.     none known
  209.  
  210.    SEE ALSO
  211. gadutil.library/GU_CheckVersion               gadutil.library/GU_CheckVersion
  212.  
  213.    NAME
  214.     GU_CheckVersion -- Check the version.revision of a library
  215.  
  216.    SYNOPSIS
  217.     success = GU_CheckVersion(library, version, revision)
  218.     D0, SR(Z)                 A0       D0       D1
  219.  
  220.     BOOL GU_CheckVersion(struct Library *, UWORD, UWORD);
  221.  
  222.    FUNCTION
  223.     Compares a library's version and revision with a required one.
  224.     
  225.    INPUTS
  226.     library  - a pointer to an opened library/device
  227.     version  - the version of the library that is required
  228.     revision - the revision of the library that is required
  229.  
  230.    RESULT
  231.     success - TRUE if the required version is older or equal to the
  232.           opened one. FALSE otherwise.
  233.     SR(Z)   - 0 if function returns TRUE, 1 otherwise
  234.  
  235.    BUGS
  236.     none known
  237.  
  238.    SEE ALSO
  239. gadutil.library/GU_ClearList                     gadutil.library/GU_ClearList
  240.  
  241.    NAME
  242.     GU_ClearList -- Clear a listview gadget and deallocate all its nodes.
  243.  
  244.    SYNOPSIS
  245.     GU_ClearList(gad, win, list)
  246.                  D0   A0   A1
  247.  
  248.     VOID GU_ClearList(struct Gadget *, struct Window *, struct List *);
  249.  
  250.    FUNCTION
  251.     Clear a listview gadget and deallocate all nodes.
  252.  
  253.    INPUTS
  254.     gad  - Gadget To Change
  255.     win  - Window that the gadget is located in.
  256.     list - List structure to deallocate nodes from.
  257.  
  258.    RESULT
  259.     none
  260.  
  261.    BUGS
  262.     none known
  263.  
  264.    SEE ALSO
  265.     GU_AddTail(), GU_NewList(), GU_DetachList(), GU_AttachList()
  266.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  267. gadutil.library/GU_ClearWindow                 gadutil.library/GU_ClearWindow
  268.  
  269.    NAME
  270.     GU_ClearWindow -- Fill the inside of a window with selected color.
  271.  
  272.    SYNOPSIS
  273.     GU_ClearWindow(window, color)
  274.                    A0      D0
  275.  
  276.     VOID GU_ClearWindow(struct Window *, UWORD);
  277.  
  278.    FUNCTION
  279.     Fills the inner area of a window with given color.
  280.  
  281.    INPUTS
  282.     window - pointer to the window to be filled
  283.  
  284.     color - the color to use. Use color 0 to clear the window.
  285.  
  286.    BUGS
  287.     none known
  288.  
  289.    SEE ALSO
  290. gadutil.library/GU_CloseCatalog               gadutil.library/GU_CloseCatalog
  291.  
  292.    NAME
  293.     GU_CloseCatalog -- Close a message catalog.
  294.  
  295.    SYNOPSIS
  296.     GU_CloseCatalog(catalog)
  297.                     A0
  298.  
  299.     VOID GU_CloseCatalog(struct Catalog *);
  300.  
  301.    FUNCTION
  302.     Concludes access to a message catalog. The usage count of the
  303.     catalog is decremented. When this count reaches 0, the catalog
  304.     can be expunged from system memory whenever a memory panic occurs.
  305.  
  306.    INPUTS
  307.     catalog - the message catalog to close. A NULL catalog is a valid
  308.           parameter and is simply ignored.
  309.  
  310.    NOTES
  311.     This function is a shortcut to the locale/CloseCatalog() function.
  312.  
  313.    SEE ALSO
  314.     GU_OpenCatalog(), GU_GetLocaleStr()
  315. gadutil.library/GU_CloseFont                     gadutil.library/GU_CloseFont
  316.  
  317.    NAME
  318.     GU_CloseFont -- Release a pointer to a system font.
  319.  
  320.    SYNOPSIS
  321.     GU_CloseFont(font)
  322.                  A0
  323.  
  324.     VOID GU_CloseFont(struct TextFont *);
  325.  
  326.    FUNCTION
  327.     This function indicates that the font specified is no longer
  328.     in use. It is used to close a font opened by GU_OpenFont, so
  329.     that fonts that are no longer in use do not consume system
  330.     resources.
  331.  
  332.    INPUTS
  333.     font - a font pointer as returned by GU_OpenFont()
  334.  
  335.    RESULT
  336.  
  337.    BUGS
  338.     none known
  339.  
  340.    SEE ALSO
  341.     GU_OpenFont()
  342. gadutil.library/GU_CoordsInGadBox           gadutil.library/GU_CoordsInGadBox
  343.  
  344.    NAME
  345.     GU_CoordsInGadBox -- Check if a coordinate pair is within a gadget.
  346.  
  347.    SYNOPSIS
  348.     IsInBox = GU_CoordsInGadBox(coords, gad)
  349.     D0,SR(Z)                    D0      A0
  350.  
  351.     BOOL GU_CoordsInGadBox(ULONG, struct Gadget *);
  352.  
  353.    FUNCTION
  354.     Check if a coordinate pair is within a gadget's border. This
  355.     function may be used to make coordinate sensitive AppWindows
  356.     (allows the user to drop a file on a string gadget etc.).
  357.     To use this function, you must save the coordinates from the
  358.     recieved message (AppMessage, IntuiMessage) to have something
  359.     to compare against.
  360.  
  361.    INPUTS
  362.     coords - a combined LONG of both the X and Y coordinates to
  363.          compare against. The X coordinate should be in the
  364.          upper word of the parameter.
  365.  
  366.     gad - the gadget to check the coordinates against.
  367.  
  368.    RESULT
  369.     IsInBox - TRUE if both given coordinates was within the gadget's
  370.           outer box (X coord is between gadx and gadx+gadw,
  371.           Y coord is between gady and gady+gadh). Otherwise this
  372.           function will return FALSE.
  373.  
  374.    EXAMPLES
  375.     Assembly language:
  376.         move.l    am_MouseX(a0),d0    ; Get X and Y coordinates
  377.         move.l    mystrgad(pc),a0
  378.         move.l    GadUtilBase(pc),a6
  379.         jsr    _LVOGU_CoordsInGadBox(a6)
  380.         beq.b    .notinbox        ; Not in gadget box
  381.     
  382.         ; Do what you want to do if the coordinates are
  383.         ; within the gadget box
  384.     .notinbox:
  385.         ; Here, you may want to check for some other gadgets
  386.  
  387.  
  388.     C:
  389.         long coords;
  390.         coords = (LONG)appmsg->MouseX << 16 | appmsg->MouseY;
  391.         if (CoordsInGadBox(coords,mystrgad) = TRUE)
  392.         {
  393.             /* Do what you want to do if the coordinates
  394.                are within the gadget box */
  395.         }
  396.         else
  397.         {
  398.             /* Here, you may want to check for some other
  399.                gadgets */
  400.         }
  401. gadutil.library/GU_CountNodes                   gadutil.library/GU_CountNodes
  402.  
  403.    NAME
  404.     GU_CountNodes -- Count number of nodes in a list.
  405.  
  406.    SYNOPSIS
  407.     numnodes = GU_CountNodes(list)
  408.     D0                       A0
  409.  
  410.     ULONG GU_CountNodes(struct List *);
  411.  
  412.    FUNCTION
  413.     This function will count the number of nodes attached to a list.
  414.  
  415.    INPUTS
  416.     list - a pointer to the list to get the number of nodes in
  417.  
  418.    RESULT
  419.     numnodes - Number of nodes that was in the list for the moment.
  420.                Note that count starts from one and not from zero!
  421.  
  422.    NOTES
  423.     Use Forbid() and Permit() around a call to this function if you
  424.     are using it on a list that can change at any time (e.g. a list
  425.     that wasn't created by yourself). This function may not be accurate
  426.     when you are using it on a system list.
  427.  
  428.    SEE ALSO
  429.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  430.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_NewList(), GU_SortList()
  431. gadutil.library/GU_CreateContext             gadutil.library/GU_CreateContext
  432.  
  433.    NAME
  434.     GU_CreateContext -- Create a space for GadTools context data.
  435.  
  436.    SYNOPSIS
  437.     gad = GU_CreateContext(glistptr)
  438.     D0                     A0
  439.  
  440.     struct Gadget *GU_CreateContext(struct Gadget **);
  441.  
  442.    FUNCTION
  443.     This function is a replacement for the GadTools version. Use this
  444.     instead. This will make your program to take advantage of future
  445.     enhancements of gadutil.
  446.  
  447.     Creates a place for GadTools to store any context data it might
  448.     need for your window.  In reality, an unselectable invisible
  449.     gadget is created, with room for the context data.
  450.     This function also establishes the linkage from a glist type
  451.     pointer to the individual gadget pointers.  Call this function
  452.     before any of the other gadget creation calls.
  453.  
  454.    INPUTS
  455.  
  456.     glistptr - Address of a pointer to a Gadget, which was previously
  457.                set to NULL.  When all the gadget creation is done, you may
  458.                use that pointer as your NewWindow.FirstGadget, or
  459.                in intuition.library/AddGList(),
  460.                intuition.library/RefreshGList(), FreeGadgets(), etc.
  461.  
  462.    RESULT
  463.     gad - pointer to context gadget, or NULL if failure.
  464.  
  465.    NOTES
  466.     Look in gadtools/CreateContext() for more information.
  467.  
  468.    SEE ALSO
  469.     gadtools/CreateContext()
  470. gadutil.library/GU_CreateGadgetA             gadutil.library/GU_CreateGadgetA
  471.  
  472.    NAME
  473.     GU_CreateGadgetA -- Create a gadget with built-in hotkey support.
  474.  
  475.    SYNOPSIS
  476.     gad = CreateGadgetA(kind, prevgad, newgad, taglist)
  477.     D0,A0               D0    A0       A1      A2
  478.  
  479.     struct Gadget *GU_CreateGadgetA(ULONG, struct Gadget *,
  480.                     struct NewGadget *, struct TagItem *);
  481.  
  482.    FUNCTION
  483.     GU_CreateGadgetA() allocates and initializes a new gadget of the
  484.     specified kind, and attaches it to the previous gadget. The gadget
  485.     is created based on the supplied kind, NewGadget structure, and
  486.     tags.
  487.  
  488.     This function differs from the GadTools equivalent by supporting
  489.     some extra tags to allow the gadget to be selected using the
  490.     keyboard.
  491.  
  492.    INPUTS
  493.     kind - kind of gadget to create. One of the XXX_KIND values
  494.            defined in <libraries/gadtools.h>.
  495.  
  496.     prevgad - pointer to the previous gadget that this new gadget
  497.           should be attached to. This function will fail if
  498.           this value is NULL.
  499.  
  500.     newgad - a filled in NewGadget structure describing the desired
  501.          gadget's size, position, label, etc.
  502.  
  503.     taglist - pointer to an array of tags providing optional extra
  504.           parameters, or NULL.
  505.  
  506.    TAGS
  507.     All kinds:
  508.  
  509.     GT_Underscore - Indicates the symbol that precedes the character
  510.         in the gadget label to be underscored. This can be to
  511.         indicate keyboard equivalents for gadgets. GadUtil has
  512.         the ability to process the keyboard equivalents if some
  513.         other tags are used.
  514.  
  515.     GU_Hotkey - This tag selects the hotkey to be used as an automatic
  516.         keyboard command for the gadget. The ti_Data field should
  517.         contain the ASCII or RAWKEY code for the hotkey.
  518.         This tag may be used together with the GU_HotkeyCase and
  519.         GU_LabelHotkey. The GU_RawKey tag requires this tag.
  520.  
  521.     GU_HotkeyCase - This tag makes the keyboard command case-sensitive.
  522.         This tag may not be used with GU_RawKey.
  523.  
  524.     GU_LabelHotkey - This tag picks the hotkey from the gadget text
  525.         field in the NewGadget structure when the gadget is created.
  526.         If no key is marked with the underscore, the GU_HotKey code
  527.         will be used.
  528.  
  529.         This tag supports and requires the GT_Underscore tag. The
  530.         character that was given in the GT_Underscore tag will be
  531.         used to find the code for the hotkey.
  532.  
  533.     GU_RawKey - This tag makes the hotkey code to a RAWKEY code. All
  534.         keys on the keyboard has one rawkey code that matches the
  535.         key.
  536.  
  537.         If your program also gets VANILLAKEY events, you must be
  538.         careful when selecting the rawkey code to be used as a
  539.         keyboard shortcut for this gadget. RAWKEY events will only
  540.         be sent for special keys (such as the HELP, Control, Alt
  541.         and function keys) that don't map to a single character. 
  542.         All keys that maps to a single character will be processed
  543.         as a VANILLAKEY event.
  544.  
  545.         This tag may not be used with (and will also disable) the
  546.         GU_HotkeyCase and GU_LabelHotkey tags.
  547.  
  548.     Kind specific tags:
  549.         See the GadTools function CreateGadgetA for all other tags.
  550.  
  551.    RESULT
  552.     gad - pointer to the new gadget, or NULL if the allocation failed
  553.           or if prevgad was NULL.
  554.  
  555.    NOTES
  556.     Note that the ng_VisualInfo and ng_TextAttr fields of the NewGadget
  557.     structure must be set to valid VisualInfo and TextAttr pointers, or
  558.     this function will fail.
  559.  
  560.    SEE ALSO
  561.     GU_FreeGadgets(), GU_SetGadgetAttrsA(), GU_GetVisualInfoA(),
  562.     GU_GetIMsg(), gadtools/CreateGadgetA, <libraries/gadtools.h>
  563. gadutil.library/GU_CreateLocMenuA           gadutil.library/GU_CreateLocMenuA
  564.  
  565.    NAME
  566.     GU_CreateLocMenuA -- Create a menu with localized items.
  567.  
  568.    SYNOPSIS
  569.     menu = GU_CreateLocMenuA(newmenu, gad_info, createtags, layouttags)
  570.     D0                       A0       A1        A2             A3
  571.  
  572.     struct Menu *GU_GetLocaleStr(struct NewMenu *, APTR,
  573.                 struct TagItem *, struct TagItem *);
  574.  
  575.    FUNCTION
  576.     Create and layout a localized menu. This function replaces both
  577.     the gadtools/CreateMenusA and gadtools/LayoutMenusA functions. See
  578.     those functions for a more in-depth description of this function.
  579.  
  580.    INPUTS
  581.     newmenu - pointer to an array of initialized struct NewMenus. This
  582.           differs from the GadTools function in that, instead of
  583.           giving pointers to strings in the nm_Label and nm_CommKey
  584.           fields of the structure, you should put a string ID in the
  585.           nm_Label field of the structure. The string must be in the
  586.           format "A\x00About...". The nm_CommKey field should be left
  587.           empty.  ^^^^^^
  588.               |    |
  589.               |    |- nm_Label field for the NewMenu structure
  590.               |
  591.               |- nm_CommKey replacement. If no keyboard shortcut,
  592.                     this field MUST CONTAIN A SPACE CHAR.
  593.                     The \x00 is a NULL character.
  594.  
  595.     gad_info - the value returned from GU_LayoutGadgetsA()
  596.  
  597.     createtags - tags for the "CreateMenusA" part of this routine. All
  598.              gadtools tags are supported (directly passed to GT).
  599.  
  600.     layouttags - tags for the "LayoutMenusA" part of this routine. All
  601.              gadtools tags are supported (directly passed to GT).
  602.  
  603.    TAGS
  604.     See the gadtools functions CreateMenusA() and LayoutMenusA().
  605.  
  606.    RESULT
  607.     menu - pointer to the resulting initialized and laid out menu structure,
  608.            ready to pass to the intuition function SetMenuStrip(), or NULL for
  609.            failure.
  610.  
  611.    SEE ALSO
  612.     GU_FreeMenus(), gadtools/CreateMenusA(), gadtools/LayoutMenusA(),
  613.     gadtools/FreeMenus()
  614. gadutil.library/GU_CreateMenusA               gadutil.library/GU_CreateMenusA
  615.  
  616.    NAME
  617.     GU_CreateMenusA -- Allocate and fill out a menu structure.
  618.  
  619.    SYNOPSIS
  620.     menu = GU_CreateMenusA(newmenu, taglist)
  621.     D0                     A0       A1
  622.  
  623.     struct Menu *GU_CreateMenusA(struct NewMenu *, struct TagItem *);
  624.  
  625.    FUNCTION
  626.     CreateMenusA() allocates and initializes a complete menu
  627.     structure based on the supplied array of NewMenu structures.
  628.     Optionally, CreateMenusA() can allocate and initialize a complete
  629.     set of menu items and sub-items for a single menu title.  This
  630.     is dictated by the contents of the array of NewMenus.
  631.  
  632.     These GadTools routines are only here to make it simpler for someone
  633.     who wants to use them. This for example, is of no use if you use the
  634.     GadUtil function GU_CreateLocMenuA() to define localized (optional)
  635.     menus with automatic hotkey handlimg etc.
  636.  
  637.    INPUTS
  638.     newmenu - pointer to an array of initialized struct NewMenus.
  639.     tagList - pointer to an array of tags providing optional extra
  640.           parameters, or NULL.
  641.  
  642.    TAGS
  643.     See gadtools/CreateMenusA() for available tags.
  644.  
  645.    RESULT
  646.     menu - pointer to the resulting initialized menu structure (or
  647.               the resulting FirstItem), with all the links for menu items
  648.               and subitems in place.
  649.               The result will be NULL if CreateMenusA() could not allocate
  650.               memory for the menus, or if the NewMenu array had an
  651.               illegal arrangement (eg. NM_SUB following NM_TITLE).
  652.               (see also the GTMN_SecondaryError tag above).
  653.  
  654.    NOTES
  655.     See gadtools/CreateMenusA() for more information.
  656.  
  657.    SEE ALSO
  658.     GU_LayoutMenusA(), GU_FreeMenus(), gadtools/CreateMenusA()
  659. gadutil.library/GU_DetachList                   gadutil.library/GU_DetachList
  660.  
  661.    NAME
  662.     GU_DetachList -- Disconnect the list from a listview gadget.
  663.  
  664.    SYNOPSIS
  665.     GU_DetachList(gad, win)
  666.                   D0   A0
  667.  
  668.     VOID GU_DetachList(struct Gadget *, struct Window *);
  669.  
  670.    FUNCTION
  671.     Detach a listview's list (without visual effect).
  672.     This has to be done before you can change anything in the list,
  673.     eg add a node, delete a node etc.
  674.  
  675.     Use GU_AttachList() to put the list back to the gadget.
  676.  
  677.    INPUTS
  678.     gad - Gadget to detach list from.
  679.     win - Window that the gadget is located in.
  680.  
  681.    RESULT
  682.     none
  683.  
  684.    BUGS
  685.     none known
  686.  
  687.    SEE ALSO
  688.     GU_AddTail(), GU_ClearList(), GU_NewList(), GU_AttachList()
  689.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  690. gadutil.library/GU_DisableGadget             gadutil.library/GU_DisableGadget
  691.  
  692.    NAME
  693.     GU_DisableGadget -- Disable / Enable a gadget.
  694.  
  695.    SYNOPSIS
  696.     GU_DisableGadget(status, gadget, window)
  697.                      D0,     A0,     A1
  698.  
  699.     VOID GU_DisableGadget(BOOL, struct Gadget *, struct Window *);
  700.  
  701.    FUNCTION
  702.     Disables or enables a gadget (that supports this).
  703.  
  704.    INPUTS
  705.     status - The new status for the gadget, TRUE for disabled, FALSE for
  706.              enabled.
  707.     gadget - A pointer to the gadget to change.
  708.     window - Pointer to the window that the gadget is placed in.
  709.  
  710.    RESULT
  711.     none
  712.  
  713.    BUGS
  714.     none known
  715.  
  716.    SEE ALSO
  717. gadutil.library/GU_DrawBevelBoxA             gadutil.library/GU_DrawBevelBoxA
  718.  
  719.    NAME
  720.     GU_DrawBevelBoxA -- Draw a bevelled box.
  721.  
  722.    SYNOPSIS
  723.     GU_DrawBevelBoxA(rport, left, top, width, height, taglist)
  724.                      A0     D0    D1   D2     D3      A1
  725.  
  726.     VOID GU_DrawBevelBoxA(struct RastPort *, WORD, WORD, WORD, WORD,
  727.                   struct TagItem *);
  728.  
  729.    FUNCTION
  730.     This function renders a bevelled box of specified dimensions
  731.     and type into the supplied RastPort.
  732.  
  733.    INPUTS
  734.     rport - RastPort into which the box is to be drawn.
  735.     left - left edge of the box.
  736.     top - top edge of the box.
  737.     width - width of the box.
  738.     height - height of the box.
  739.     tagList - pointer to an array of tags providing extra parameters
  740.  
  741.    RESULT
  742.     none
  743.  
  744.    NOTES
  745.     See gadtools/DrawBevelBoxA() for more information.
  746.  
  747.    SEE ALSO
  748.     GU_GetVisualInfoA(), gadtools/DrawBevelBoxA()
  749. gadutil.library/GU_EndRefresh                   gadutil.library/GU_EndRefresh
  750.  
  751.    NAME
  752.     GU_EndRefresh -- End refreshing friendly to GadTools.
  753.  
  754.    SYNOPSIS
  755.     GU_EndRefresh(win, complete)
  756.                   A0   D0
  757.  
  758.     VOID GU_EndRefresh(struct Window *, BOOL);
  759.  
  760.    FUNCTION
  761.  
  762.     Invokes the intuition.library/EndRefresh() function in a manner
  763.     friendly to the Gadget Toolkit.  This function call permits
  764.     GadTools gadgets to refresh themselves at the correct time.
  765.     Call this function to EndRefresh() when you have used
  766.     GU_BeginRefresh().
  767.  
  768.    INPUTS
  769.     win - pointer to Window structure for which a IDCMP_REFRESHWINDOW
  770.           IDCMP event was received.
  771.     complete - TRUE when done with refreshing.
  772.  
  773.    NOTES
  774.     See gadtools/GT_EndRefresh for more information.
  775.  
  776.    SEE ALSO
  777.     GU_BeginRefresh(), gadtools/GT_EndRefresh(), intuition/EndRefresh()
  778. gadutil.library/GU_FilterIMsg                   gadutil.library/GU_FilterIMsg
  779.  
  780.    NAME
  781.     GU_FilterIMsg -- Filter an IntuiMessage through GadTools.
  782.  
  783.    SYNOPSIS
  784.     modimsg = GU_FilterIMsg(imsg)
  785.     D0                      A1
  786.  
  787.     struct IntuiMessage *GU_FilterIMsg(struct IntuiMessage *);
  788.  
  789.    FUNCTION
  790.     NOTE WELL:  Extremely few programs will actually need this function.
  791.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  792.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  793.  
  794.     GT_FilterIMsg() takes the supplied IntuiMessage and asks the
  795.     Gadget Toolkit to consider and possibly act on it.  Returns
  796.     NULL if the message was only of significance to a GadTools gadget
  797.     (i.e. not to you), else returns a pointer to a modified IDCMP
  798.     message, which may contain additional information.
  799.  
  800.     You should examine the Class, Code, and IAddress fields of
  801.     the returned message to learn what happened.  Do not make
  802.     interpretations based on the original imsg.
  803.  
  804.     You should use GT_PostFilterIMsg() to revert to the original
  805.     IntuiMessage once you are done with the modified one.
  806.  
  807.    INPUTS
  808.     imsg - an IntuiMessage you obtained from a Window's UserPort.
  809.  
  810.    RESULT
  811.     modimsg - a modified IntuiMessage, possibly with extra information
  812.               from GadTools, or NULL. When NULL, the message passed in to
  813.           the function should be sent back to Intuition via ReplyMsg().
  814.  
  815.    NOTES
  816.     See gadtools/GT_FilterIMsg() for more information.
  817.  
  818.    SEE ALSO
  819.     GU_GetIMsg(), GU_PostFilterIMsg(), gadtools/GT_FilterIMsg()
  820. gadutil.library/GU_FindNode                       gadutil.library/GU_FindNode
  821.  
  822.    NAME
  823.     GU_FindNode -- Find the node structure of a given node number
  824.  
  825.    SYNOPSIS
  826.     node = GU_FindNode(list, number)
  827.     D0,A0,SR(Z)        A0    D0
  828.  
  829.     struct Node *GU_FindNode(struct List *, WORD);
  830.  
  831.    FUNCTION
  832.     Finds a specified node in a list.
  833.  
  834.    INPUTS
  835.     list   - Struct List. The list in where to search.
  836.     number - Number of the node to find (counting from 0).
  837.  
  838.    RESULT
  839.     node  - Address to the node structure or NULL if the node wasn't
  840.             existing.
  841.  
  842.     SR(Z) - 0 for success, 1 for failure.
  843.  
  844.    BUGS
  845.     none known
  846.  
  847.    SEE ALSO
  848.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  849.     GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_NewList(), GU_SortList()
  850. gadutil.library/GU_FreeGadgets                 gadutil.library/GU_FreeGadgets
  851.  
  852.    NAME
  853.     GU_FreeGadgets -- Free a linked list of gadgets.
  854.  
  855.    SYNOPSIS
  856.     GU_FreeGadgets(glist)
  857.                    A0
  858.  
  859.     VOID GU_FreeGadgets(struct Gadget *);
  860.  
  861.    FUNCTION
  862.     Frees all gadgets found on the linked list of gadgets beginning
  863.     with the specified one. Frees all the memory that was allocated
  864.     by GU_CreateGadgetA(). This function will return safely with no
  865.     action if it recieves a NULL parameter.
  866.  
  867.     Use this function in place of gadtools/FreeGadgets().
  868.  
  869.    INPUTS
  870.     glist - pointer to the first gadget in list to be freed
  871.  
  872.    SEE ALSO
  873.     GU_CreateGadgetA() , gadtools/FreeGadgets().
  874. gadutil.library/GU_FreeInput                     gadutil.library/GU_FreeInput
  875.  
  876.    NAME
  877.     GU_FreeInput -- Unblock input to a blocked window.
  878.  
  879.    SYNOPSIS
  880.     GU_FreeInput(window)
  881.                  A0
  882.  
  883.     VOID GU_FreeInput(struct Window *);
  884.  
  885.    FUNCTION
  886.     Unblock a window's user input. Call this function after blocking
  887.     the input with GU_BlockInput().
  888.  
  889.    INPUTS
  890.     window - the window that was blocked with GU_BlockInput().
  891.  
  892.    EXAMPLE
  893.  
  894.     BlockInput(myWin);
  895.     About();
  896.     FreeInput();
  897.  
  898.     Will block the parent window for user input while displaying the
  899.     About requester of a program.
  900.  
  901.    SEE ALSO
  902.     GU_BlockInput()
  903. gadutil.library/GU_FreeLayoutGadgets     gadutil.library/GU_FreeLayoutGadgets
  904.  
  905.    NAME
  906.     GU_FreeLayoutGadgets -- Frees gadgets laid out with GU_LayoutGadgetsA().
  907.  
  908.    SYNOPSIS
  909.     GU_FreeLayoutGadgets(gad_info)
  910.                              A0
  911.  
  912.     VOID GU_FreeLayoutGadgets(APTR);
  913.  
  914.    FUNCTION
  915.     Frees gadgets laid out with LayoutGadgetsA().
  916.  
  917.    INPUTS
  918.     gad_info - The pointer returned by LayoutGadgetsA().
  919.  
  920.    RESULT
  921.     none
  922.  
  923.    SEE ALSO
  924. gadutil.library/GU_FreeMenus                     gadutil.library/GU_FreeMenus
  925.  
  926.    NAME
  927.     GU_FreeMenus -- Frees memory allocated by GU_CreateMenusA().
  928.  
  929.    SYNOPSIS
  930.     GU_FreeMenus(menu)
  931.                  A0
  932.  
  933.     VOID GU_FreeMenus(struct Menu *);
  934.  
  935.    FUNCTION
  936.     Frees the menus allocated by GU_CreateMenusA().  It is safe to
  937.     call this function with a NULL parameter.
  938.  
  939.    INPUTS
  940.     menu - pointer to menu structure (or first MenuItem) obtained
  941.            from GU_CreateMenusA().
  942.  
  943.    NOTES
  944.     See gadtools/FreeMenus() for more information.
  945.  
  946.    SEE ALSO
  947.     GU_CreateMenusA(), gadtools/FreeMenus()
  948. gadutil.library/GU_FreeVisualInfo           gadutil.library/GU_FreeVisualInfo
  949.  
  950.    NAME
  951.     GU_FreeVisualInfo -- Return any resources taken by GU_GetVisualInfoA
  952.  
  953.    SYNOPSIS
  954.     GU_FreeVisualInfo(vi)
  955.                       A0
  956.  
  957.     VOID GU_FreeVisualInfo(APTR);
  958.  
  959.    FUNCTION
  960.     FreeVisualInfo() returns any memory or other resources that
  961.     were allocated by GetVisualInfoA(). You should only call this
  962.     function once you are done with using the gadgets (i.e. after
  963.         CloseWindow()), but while the screen is still valid (i.e. before
  964.         CloseScreen() or UnlockPubScreen()).
  965.  
  966.    INPUTS
  967.     vi - pointer that was obtained by calling GetVisualInfoA(). This
  968.          value may be NULL.
  969.  
  970.    NOTES
  971.     See gadtools/FreeVisualInfo() for more information.
  972.  
  973.    SEE ALSO
  974.     GU_GetVisualInfoA(), gadtools/FreeVisualInfo()
  975. gadutil.library/GU_GadgetArrayIndex       gadutil.library/GU_GadgetArrayIndex
  976.  
  977.    NAME
  978.     GU_GadgetArrayIndex -- Get a gadget's index in the LayoutGadget array.
  979.  
  980.    SYNOPSIS
  981.     index = GU_GadgetArrayIndex(id, gadgets)
  982.     D0,D1,SR(Z)                 D0  A0
  983.  
  984.     WORD GU_GadgetArrayIndex(WORD, struct LayoutGadget *);
  985.  
  986.    FUNCTION
  987.     Get a gadget's index in the Layoutgadget structure.
  988.    INPUTS
  989.     id      - The ID of the gadget you want to find.
  990.     gadgets - The LayoutGadget array that this gadget is defined in.
  991.  
  992.    RESULT
  993.     index - The index into the LayoutGadget array of the entry with the
  994.             gadget ID you asked for. Returns -1 for failure.
  995.  
  996.     SR(Z) - Set for failure. Cleared otherwise. Probably only usable for
  997.             assembly language programmers.
  998.  
  999.    SEE ALSO
  1000. gadutil.library/GU_GetGadgetAttrsA         gadutil.library/GU_GetGadgetAttrsA
  1001.  
  1002.    NAME
  1003.     GU_GetGadgetAttrsA -- Request the attributes of a GadTools gadget.
  1004.  
  1005.    SYNOPSIS
  1006.     numProcessed = GU_GetGadgetAttrsA(gad, win, req, taglist)
  1007.     D0                                A0   A1   A2   A3
  1008.  
  1009.     LONG *GU_GetGadgetAttrsA(struct Gadget *, struct Window *,
  1010.                  struct Requester *, struct TagItem *);
  1011.  
  1012.    FUNCTION
  1013.     Retrieve the attributes of the specified gadget, according to the
  1014.     attributes chosen in the tag list.  For each entry in the tag list,
  1015.     ti_Tag identifies the attribute, and ti_Data is a pointer to
  1016.     the long variable where you wish the result to be stored.
  1017.  
  1018.    INPUTS
  1019.     gad     - Pointer to the gadget in question, may be NULL.
  1020.     win     - Pointer to the window containing the gadget
  1021.     req     - Reserved for future use, should always be NULL
  1022.     taglist - Pointer to a TagItem list
  1023.  
  1024.    RESULT
  1025.     numProcessed - The number of attributes successfully filled in.
  1026.  
  1027.    NOTES
  1028.     See gadtools/GT_GetGadgetAttrsA() for tags and examples.
  1029.  
  1030.     Requires kickstart 3.0 (V39).
  1031.  
  1032.    SEE ALSO
  1033.     GU_SetGadgetAttrsA(), gadtools/GT_GetGadgetAttrsA()
  1034. gadutil.library/GU_GetGadgetPtr               gadutil.library/GU_GetGadgetPtr
  1035.  
  1036.    NAME
  1037.     GU_GetGadgetPtr -- Get a pointer to a gadget's gadget structure.
  1038.  
  1039.    SYNOPSIS
  1040.     gad = GU_GetGadgetPtr(id, gadgets)
  1041.     D0,SR(Z)              D0  A0
  1042.  
  1043.     APTR GU_GetGadgetPtr(UWORD, struct LayoutGadget *);
  1044.  
  1045.    FUNCTION
  1046.     Find a gadget's gadget structure by giving its ID. The gadget
  1047.     pointer is always found last in the LayoutGadget structure. You
  1048.     can use this function to get that pointer.
  1049.     It is also possible to get the gadget structure by taking it
  1050.     directly from the LayoutGadget structure array, but then you
  1051.     must know exactly in which structure it is located. Assembly
  1052.     language programmers can use a PC relative pointer to get the
  1053.     gadget pointer.
  1054.     
  1055.    INPUTS
  1056.     id - the ID of the gadget to search for
  1057.  
  1058.     gadgets - a pointer to the array of LayoutGadget structures.
  1059.  
  1060.    RESULT
  1061.     gad - pointer to the requested gadget. For bevelboxes, this
  1062.           function will return a BBoxData structure.
  1063.  
  1064.    EXAMPLE
  1065.  
  1066.      Some of the LayoutGadget structures from BetterTest.c:
  1067.  
  1068.      struct LayoutGadget gadgets[] = {
  1069.     { MSG_NEXTDRIVE, NextDriveGad, StdGTTags,   NULL },
  1070.     { MSG_PREVDRIVE, PrevDriveGad, StdGTTags,   NULL },
  1071.     { MSG_DRIVE,     DriveGad,     DriveGTTags, NULL },
  1072.     { MSG_REQUESTER, ReqGad,       StdGTTags,   NULL },
  1073.     { MSG_CHECKME,   CheckBoxGad,  StdGTTags,   NULL },
  1074.     { MSG_FILENAME,  FileNameGad,  StdGTTags,   NULL },
  1075.     { -1,            NULL,         NULL,        NULL }
  1076.      };
  1077.  
  1078.     The examples should get the gadget structure of the Requester
  1079.     gadget (not assuming that ID's begin with 0).
  1080.     There is two methods you can use to get a gadgets structure:
  1081.  
  1082.     1. Use the pointer in the array directly:
  1083.  
  1084.     thegadget = gadgets[3].lg_Gadget
  1085.  
  1086.     This will only work if you know in which LayoutGadget structure
  1087.     the gadget is in.
  1088.  
  1089.     2. Use this library function:
  1090.  
  1091.     thegadget = GU_GetGadgetPtr(MSG_REQUESTER, gadgets);
  1092.  
  1093.     This will always work if all gadgets have a unique ID.
  1094.  
  1095.  
  1096.      Some of the LayoutGadget structures from BetterTest.s:
  1097.  
  1098.     gadgets:
  1099.      GADGET  MSG_NEXTDRIVE,  NextDriveGad,   StdGTTags
  1100.      GADGET  MSG_PREVDRIVE,  PrevDriveGad,   StdGTTags
  1101.      GADGET  MSG_DRIVE,      DriveGad,       DriveGTTags
  1102.      GADGET  MSG_REQUESTER,  ReqGad,         StdGTTags
  1103.      GADGET  MSG_CHECKME,    CheckBoxGad,    StdGTTags
  1104.      GADGET  MSG_FILENAME,   FileNameGad,    StdGTTags
  1105.      GADGET  -1,NULL,NULL
  1106.  
  1107.      Assembly language programmers can use three methods to get the
  1108.      pointer:
  1109.  
  1110.     1. Use the pointer in the array directly:
  1111.  
  1112.         lea.l    gadgets(pc),a0    ; Get array
  1113.         moveq.l    #lg_SIZEOF,d0    ; Get the size of the LayoutGadget
  1114.         mulu    #3,d0        ;  struct and calculate offset to
  1115.                     ;  the right structure in the array
  1116.         move.l    lg_Gadget(a0,d0.l),d0    ; Get the gadget pointer
  1117.  
  1118.     This will only work if you know in which LayoutGadget structure
  1119.     the gadget is in.
  1120.  
  1121.     2. Use this library function:
  1122.  
  1123.         lea.l    gadgets(pc),a0    ; Get array
  1124.         moveq.l    #MSG_REQUESTER,d0    ; Gadget to search for
  1125.         jsr    _LVOGU_GetGadgetPtr(a6)    ; Get gadget, result in D0
  1126.  
  1127.     This will always work if all gadgets have a unique ID.
  1128.  
  1129.     3. Use an extra label for each gadget that should be easy to
  1130.        access:
  1131.  
  1132.     gadgets:
  1133.      GADGET  MSG_NEXTDRIVE,  NextDriveGad,   StdGTTags
  1134.      GADGET  MSG_PREVDRIVE,  PrevDriveGad,   StdGTTags
  1135.      GADGET  MSG_DRIVE,      DriveGad,       DriveGTTags
  1136.      GADGET  MSG_REQUESTER,  ReqGad,         StdGTTags
  1137.     reqgad:        equ    *-4
  1138.      GADGET  MSG_CHECKME,    CheckBoxGad,    StdGTTags
  1139.      GADGET  MSG_FILENAME,   FileNameGad,    StdGTTags
  1140.     filenamegad:    equ    *-4
  1141.      GADGET  -1,NULL,NULL
  1142.  
  1143.         move.l    reqgad(pc),d0        ; Get the gadget
  1144.  
  1145.     This will always work.
  1146. gadutil.library/GU_GetIMsg                         gadutil.library/GU_GetIMsg
  1147.  
  1148.    NAME
  1149.     GU_GetIMsg -- Get an IntuiMessage, process GadTools & Hotkey events.
  1150.  
  1151.    SYNOPSIS
  1152.     imsg = GU_GetIMsg(intuiport)
  1153.     D0,A0,SR(Z)       A0
  1154.  
  1155.     struct IntuiMessage *GU_GetIMsg(struct MsgPort *);
  1156.  
  1157.    FUNCTION
  1158.     Use GU_GetIMsg() in place of the usual exec.library/GetMsg() when
  1159.     reading IntuiMessages from your window's UserPort. If needed, the
  1160.     GadTools dispatcher will be invoked, and suitable processing will
  1161.     be done for gadget actions.
  1162.     If the message is an IDCMP_VANILLAKEY or an IDCMP_RAWKEY, this
  1163.     routine will search through all gadgets    for that key, and if it is
  1164.     found, the message will change to the type of message that gadget
  1165.     is supposed to send. If the key is not used as a hotkey, the
  1166.     message will not change. 
  1167.     If there are no messages (or if the only messages are meaningful
  1168.     only to GadTools/GadUtil), NULL will be returned.
  1169.  
  1170.    INPUTS
  1171.     intuiport - the Window->UserPort of a window that is using the
  1172.         GadUtil library.
  1173.  
  1174.    RESULT
  1175.     imsg - pointer to modified IntuiMessage, or NULL if there are
  1176.            no applicable messages.
  1177.  
  1178.     SR (Z) - the zero flag will be set if there was no message. This
  1179.            is probably only useful for assembly language programmers.
  1180.  
  1181.    NOTES
  1182.     Be sure to use GU_ReplyIMsg() and not exec.library/ReplyMsg() on
  1183.     messages obtained with GU_GetIMsg().
  1184.     If you intend to do more with the resulting message than read its
  1185.     fields, act on it, and reply it, you may find GU_FilterIMsg()
  1186.     more appropriate.
  1187.  
  1188.     Starting with V39 (of the OS), this function actually returns a
  1189.     pointer to an ExtIntuiMessage structure, but the prototype was
  1190.     not changed for source code compatibility with older software.
  1191.  
  1192.    SEE ALSO
  1193.     GU_ReplyIMsg(), GU_FilterIMsg()
  1194. gadutil.library/GU_GetLocaleStr               gadutil.library/GU_GetLocaleStr
  1195.  
  1196.    NAME
  1197.     GU_GetLocaleStr -- Get a localized string from a catalog.
  1198.  
  1199.    SYNOPSIS
  1200.     string = GU_GetLocaleStr(stringID, catalog, defstrings)
  1201.     D0,A0                    D0        A0       A1
  1202.  
  1203.     STRPTR GU_GetLocaleStr(ULONG, struct Catalog *, struct AppString *);
  1204.  
  1205.    FUNCTION
  1206.     Get a localized string, or the default string, from a catalog or from
  1207.     the programs built-in strings.
  1208.  
  1209.    INPUTS
  1210.     stringID - the ID of the string to get
  1211.  
  1212.     catalog - the opened catalog for the program
  1213.  
  1214.     defstrings - an array of AppString structures, the programs built-in
  1215.              strings and ID's.
  1216.  
  1217.    RESULT
  1218.     string - the address of the localized string, or if the catalog was not
  1219.          available (or if the selected language was the programs built-
  1220.          ins), a pointer to the default string with the given ID.
  1221.  
  1222.    SEE ALSO
  1223.     GU_OpenCatalog(), GU_CloseCatalog()
  1224. gadutil.library/GU_GetVisualInfoA           gadutil.library/GU_GetVisualInfoA
  1225.  
  1226.    NAME
  1227.     GU_GetVisualInfoA -- Get information GadTools needs for visuals.
  1228.  
  1229.    SYNOPSIS
  1230.     vi = GU_GetVisualInfoA(screen, taglist)
  1231.     D0                     A0      A1
  1232.  
  1233.     APTR GU_GetVisualInfoA(struct Screen *, struct TagItem *);
  1234.  
  1235.    FUNCTION
  1236.  
  1237.     Get a pointer to a (private) block of data containing various bits
  1238.     of information that GadTools needs to ensure the best quality
  1239.     visuals.  Use the result in the NewGadget structure of any gadget
  1240.     you create, or as a parameter to the various menu calls.  Once the
  1241.     gadgets/menus are no longer needed (after the last CloseWindow()),
  1242.     call FreeVisualInfo().
  1243.  
  1244.    INPUTS
  1245.     screen - pointer to the screen you will be opening on. This parameter
  1246.          may be NULL, in which case this function fails.
  1247.     tagList - pointer to an array of tags providing optional extra
  1248.           parameters, or NULL.
  1249.  
  1250.    RESULT
  1251.     vi - pointer to private data, or NULL for failure
  1252.  
  1253.    NOTES
  1254.     See gadtools/GetVisualInfoA() for more information.
  1255.  
  1256.    SEE ALSO
  1257.     GU_FreeVisualInfo(), gadtools/FreeVisualInfo(), intuition/LockPubScreen(),
  1258.     intuition/UnlockPubScreen()
  1259. gadutil.library/GU_LayoutGadgetsA           gadutil.library/GU_LayoutGadgetsA
  1260.  
  1261.    NAME
  1262.     GU_LayoutGadgetsA -- Formats an array of GadTools gadgets.
  1263.  
  1264.    SYNOPSIS
  1265.     gad_info = GU_LayoutGadgetsA(gad_list, gadgets, screen, taglist)
  1266.     D0,A0                        A0        A1       A2      A3
  1267.  
  1268.     APTR GU_LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
  1269.         struct Screen *, struct TagItem *);
  1270.  
  1271.    FUNCTION
  1272.     Creates a laid-out gadget list from a LayoutGadget array, which
  1273.     describes each gadget you want to create. Gadgets you create can
  1274.     be any of the gadget kinds supported by GadTools, as well as any
  1275.     of the extended gadget kinds provided by GadUtil.
  1276.     The gadgets created by this routine, can easily be defined so that
  1277.     they adjust their sizes and positions to accomodate fonts of any
  1278.     size, and also adapt to different locale strings.
  1279.     
  1280.    INPUTS
  1281.     gad_list - a pointer to the gadget list pointer. This will be
  1282.            ready to pass to OpenWindowTagList() or AddGList().
  1283.  
  1284.     gadgets - an array of LayoutGadget structures. Each element in
  1285.           the array describes one of the gadgets that you will
  1286.           be creating. Each LayoutGadget structure in the array
  1287.           should be initialized as follows:
  1288.  
  1289.           lg_GadgetID - the ID for this gadget. An ID of -1
  1290.                 terminates the array.
  1291.  
  1292.           lg_LayoutTags - tags that describes each gadget to
  1293.                   create. These tags is used to calculate
  1294.                   positions, sizes and other attributes
  1295.                   of the created gadgets.
  1296.  
  1297.           lg_GadToolsTags - additional tags for GadTools gadgets.
  1298.                     This would be the same set of tags that
  1299.                     you might pass to CreateGadgetA() if
  1300.                     you were using GadTools directly.
  1301.  
  1302.           lg_Gadget - the pointer to the Gadget structure created
  1303.                   for this gadget will be placed here. You
  1304.                   should initialize this field to NULL. The
  1305.                   gadget structure created should be considered
  1306.                   READ ONLY! This field will contain a pointer
  1307.                   to a struct BBoxData, if the created gadget
  1308.                   kind is a BEVELBOX_KIND or a LABEL_KIND.
  1309.  
  1310.           Assembly language programmers can use the macro GADGET:
  1311.  
  1312.             GADGET GadgetID, Gad_LayoutTags, Gad_GadToolsTags
  1313.  
  1314.     screen - a pointer to the screen that the gadgets will be created
  1315.          for. This is required, so that the layuot routines can
  1316.          get display info about the screen where the rendering
  1317.          will be done. Use LockPubScreen() to use a public screen,
  1318.          or OpenScreenTagList(), if you want to use your own screen.
  1319.  
  1320.     taglist - pointer to an array of tags providing optional extra
  1321.           parameters, or NULL.
  1322.  
  1323.                   These tags can be used here:
  1324.  
  1325.                     GU_RightExtreme (ULONG *)
  1326.                       A pointer to a longword that is used to store the
  1327.                       rightmost point that a gadget will exist in.
  1328.  
  1329.                     GU_LowerExtreme (ULONG *)
  1330.                       A pointer to a longword that is used to store the
  1331.                       lowermost point that a gadget woll exist in.
  1332.  
  1333.                     GU_Catalog (struct Catalog *)
  1334.                       A pointer to the programs translation catalog. NULL
  1335.                       indicates that the program should use the internal
  1336.                       strings. You must open the catalog by yourself (use
  1337.                       GU_OpenCatalog() or locale/OpenCatalog). The
  1338.                       GU_AppStrings tag MUST be used together with this tag.
  1339.  
  1340.                     GU_DefTextAttr (struct TextAttr *)
  1341.                       Specifies the default font to use with all gadgets. Can
  1342.                       be overridden with GU_TextAttr tag for each gadget.
  1343.  
  1344.                     GU_AppStrings (struct AppString *)
  1345.                       A pointer to an array of AppString structures. These
  1346.                       strutures contains the programs internal strings. This
  1347.                       tag must be used together with the GU_Catalog tag.
  1348.  
  1349.                     GU_BorderLeft (ULONG)
  1350.                       Size of the window's left border.
  1351.  
  1352.                     GU_BorderTop (ULONG)
  1353.                       Size of the window's top border.
  1354.  
  1355.                     GU_NoCreate (BOOL)
  1356.                       Don't create any gadgets. Useful to determine if the
  1357.                       window will fit on the screen etc.
  1358.  
  1359.                     GU_MinimumIDCMP (ULONG *)
  1360.                       A pointer to a longword that is used to store the
  1361.                       minimum required IDCMP flags, so that all gadgets will
  1362.                       work. The longword can already be initialized, and any
  1363.                       new needed IDCMP flags will be appended to that
  1364.                       longword.
  1365.  
  1366.    TAGS
  1367.  
  1368.    Tags for the gadgets lg_LayoutTags taglist. The other tags can be found in
  1369.    the autodoc to gadtools.library/CreateGadgetA().
  1370.  
  1371.    GU_GadgetKind (ULONG)
  1372.       Can be any of the standard GadTools gadget kinds, or one of the
  1373.       extensions provided by GadUtil. Currently extended types are:
  1374.  
  1375.          IMAGE_KIND
  1376.            A gadget that uses an Intuition Image structure for its
  1377.            contents. Selected and unselected states can use different
  1378.            images. The images are centered automatically.
  1379.  
  1380.            Extra tags for IMAGE_KIND:
  1381.  
  1382.               GUIM_Image (struct Image *)
  1383.                  Image for the gadget in its unselected state. This is
  1384.                  the only required (extra) tag for IMAGE_KIND gadgets.
  1385.  
  1386.               GUIM_SelectImg (struct Image *)
  1387.                  Image for the gadget in its selected state. If this tag
  1388.                  is omitted, the selected image will be the same as the
  1389.                  unselected, and only the border and the background color
  1390.                  will change (depending on the GUIM_BOOPSILook tag).
  1391.  
  1392.               GUIM_ReadOnly (BOOL)
  1393.                  TRUE to create a read-only image gadget.
  1394.  
  1395.               GUIM_BOOPSILook (BOOL)
  1396.                  This tag will allow the programmer to select how the
  1397.                  secondary image should be shown, if only one image is
  1398.                  used for the gadget. Defaults to TRUE, which means that
  1399.                  the background color will change when the user selects
  1400.                  the gadget.
  1401.  
  1402.          DRAWER_KIND
  1403.            A "select drawer" image button. This can be used to select
  1404.            a path, but is often used to select files.
  1405.  
  1406.          FILE_KIND
  1407.            A "select file" image button. This can be used to allow the
  1408.            user to select a file. Most programs uses the DRAWER_KIND
  1409.            for both file and path selection.
  1410.  
  1411.          BEVELBOX_KIND
  1412.            A GadTools bevelbox. Use this to avoid the use of absolute
  1413.            sizing of bevelboxes. All bevel box kinds from OS3.0 is
  1414.            supported, even if the computer only has OS2.0.
  1415.  
  1416.            The function GU_RefreshBoxes() can be used to redraw all
  1417.            bevelboxes.
  1418.  
  1419.            Extra tags for BEVELBOX_KIND:
  1420.  
  1421.               GUBB_Recessed (BOOL)
  1422.                  Create a recessed ("pushed in") bevel box. Differs from
  1423.                  the GadTools tag GTBB_Recessed, in that it works with
  1424.                  both TRUE and FALSE as parameter. GadTools creates a
  1425.                  recessed box independent from the given value.
  1426.  
  1427.                  Defaults to FALSE.
  1428.  
  1429.               GUBB_FrameType (ULONG)
  1430.                  Determines what kind of box this function renders. The
  1431.                  current available alternatives are:
  1432.  
  1433.                     BFT_BUTTON - Generates a box like what is used around
  1434.                                  a GadTools BUTTON_KIND gadget.
  1435.  
  1436.                     BFT_RIDGE - Generates a box like what is used around
  1437.                                 a GadTools STRING_KIND gadget.
  1438.  
  1439.                     BFT_DROPBOX - Generates a box suitable for a standard
  1440.                                   icon drop box imagery.
  1441.  
  1442.                     BFT_HORIZBAR - Generates a horizontal shadowed line.
  1443.                                    Can also be used to draw a normal line,
  1444.                                    using 1 for the line's height.
  1445.  
  1446.                     BFT_VERTBAR - Generates a vertical shadowed line. Can
  1447.                                   also be used to draw a normal line, using
  1448.                                   1 for the line's width.
  1449.  
  1450.                  Defaults to BFT_BUTTON.
  1451.  
  1452.               GUBB_TextColor (ULONG)
  1453.                  Selects which color to print the title text in. Only useful
  1454.                  for a bevelbox with a title. Defaults to the color of the
  1455.                  TEXTPEN.
  1456.  
  1457.               GUBB_TextPen (ULONG)
  1458.                  Selects which pen to print the title text in. Only
  1459.                  useful for a bevelbox with a title. Defaults to TEXTPEN.
  1460.                  This tag overrides the GUBB_TextColor tag.
  1461.  
  1462.               GUBB_Flags (ULONG)
  1463.                  Flags for text placement, text shadowing and 3D text:
  1464.  
  1465.                  Y-pos flags
  1466.                  ~~~~~~~~~~~
  1467.                     BB_TEXT_ABOVE - Places the bevel box text above the upper
  1468.                                     border of the box           ___Example___
  1469.  
  1470.                     BB_TEXT_IN    - Places the bevel box text at the upper
  1471.                                     border of the box           ---Example---
  1472.  
  1473.                     BB_TEXT_BELOW - Places the bevel box text below the upper
  1474.                                     border of the box           ___       ___
  1475.                                                                    Example
  1476.                  X-pos flags
  1477.                  ~~~~~~~~~~~
  1478.                     BB_TEXT_CENTER - Places the bevel box text in the middle
  1479.                                      of the upper border        ---Example---
  1480.  
  1481.                     BB_TEXT_LEFT   - Places the bevel box text 8 pixels from
  1482.                                      the left edge of the box   -Example-----
  1483.  
  1484.                     BB_TEXT_RIGHT  - Places the bevel box text 8 pixels from
  1485.                                      the right edge of the box  -----Example-
  1486.  
  1487.                  Combined flags
  1488.                  ~~~~~~~~~~~~~~
  1489.                     BB_TEXT_ABOVE_CENTER - BB_TEXT_ABOVE + BB_TEXT_CENTER
  1490.                     BB_TEXT_ABOVE_LEFT   - BB_TEXT_ABOVE + BB_TEXT_LEFT
  1491.                     BB_TEXT_ABOVE_RIGHT  - BB_TEXT_ABOVE + BB_TEXT_RIGHT
  1492.  
  1493.                     BB_TEXT_IN_CENTER    - BB_TEXT_IN + BB_TEXT_CENTER
  1494.                     BB_TEXT_IN_LEFT      - BB_TEXT_IN + BB_TEXT_LEFT
  1495.                     BB_TEXT_IN_RIGHT     - BB_TEXT_IN + BB_TEXT_RIGHT
  1496.  
  1497.                     BB_TEXT_BELOW_CENTER - BB_TEXT_BELOW + BB_TEXT_CENTER
  1498.                     BB_TEXT_BELOW_LEFT   - BB_TEXT_BELOW + BB_TEXT_LEFT
  1499.                     BB_TEXT_BELOW_RIGHT  - BB_TEXT_BELOW + BB_TEXT_RIGHT
  1500.  
  1501.                  Default is BB_TEXT_ABOVE|BB_TEXT_CENTER. Combine the x and y
  1502.                  position flags by OR:ing them together. Don't combine two X
  1503.                  or two Y flags together.
  1504.                 
  1505.                  Shadow placement flags
  1506.                  ~~~~~~~~~~~~~~~~~~~~~~
  1507.                     BB_SHADOW_DR - Places the bevel box text shadow one pixel
  1508.                                    below and to the right of the text. 
  1509.  
  1510.                     BB_SHADOW_UR - Places the bevel box text shadow one pixel
  1511.                                    above and to the right of the text. 
  1512.  
  1513.                     BB_SHADOW_DL - Places the bevel box text shadow one pixel
  1514.                                    below and to the left of the text. 
  1515.  
  1516.                     BB_SHADOW_UL - Places the bevel box text shadow one pixel
  1517.                                    above and to the left of the text. 
  1518.  
  1519.                     BB_SUNAT_UL  - Another name for BB_SHADOW_DR
  1520.                     BB_SUNAT_DL  - Another name for BB_SHADOW_UR
  1521.                     BB_SUNAT_UR  - Another name for BB_SHADOW_DL
  1522.                     BB_SUNAT_DR  - Another name for BB_SHADOW_UL
  1523.  
  1524.                  Default is BB_SHADOW_DR (BB_SUNAT_UL).
  1525.  
  1526.                     BB_3DTEXT    - This flag can be used in place of the tag
  1527.                                    GUBB_3DText, TRUE
  1528.  
  1529.               GUBB_3DText (BOOL)
  1530.                  Enables the shadow on the bevel box text. This tag must be
  1531.                  used if GUBB_ShadowColor or GUBB_ShadowPen isn't used.
  1532.                  Another way to enable 3D text is to set the flag BB_3DTEXT
  1533.                  in the GUBB_Flags tag.
  1534.  
  1535.               GUBB_ShadowColor (ULONG)
  1536.                  Selects which color to print the shadow text in. Only useful
  1537.                  for a bevelbox with a title. Defaults to the color of the
  1538.                  SHADOWPEN.
  1539.  
  1540.               GUBB_ShadowPen (ULONG)
  1541.                  Selects which pen to print the shadow text in. Only useful
  1542.                  for a bevelbox with a title. Defaults to SHADOWPEN.
  1543.                  This tag overrides the GUBB_ShadowColor tag.
  1544.  
  1545.          PROGRESS_KIND
  1546.            Gadget used to display a value out of a total. Can be used to
  1547.            display the progress of a search, a diskcopy or anything else.
  1548.  
  1549.            Extra tags for PROGRESS_KIND:
  1550.  
  1551.               GUPR_FillColor (ULONG)
  1552.                  Selects which color to use to paint the current value of
  1553.                  the progress requester with. Defaults to the color of the
  1554.                  FILLPEN.
  1555.  
  1556.               GUPR_FillPen (ULONG)
  1557.                  Selects which pen to use to paint the current value of
  1558.                  the progress requester with. Defaults to the FILLPEN.
  1559.                  This tag overrides the GUPR_FillColor tag.
  1560.  
  1561.               GUPR_BackColor (ULONG)
  1562.                  Selects which color to fill the background of the progress
  1563.                  requester with. Defaults to the color of the BACKGROUNDPEN.
  1564.  
  1565.               GUPR_BackPen (ULONG)
  1566.                  Selects which pen to fill the background of the progress
  1567.                  requester with. Defaults to the BACKGROUNDPEN.
  1568.                  This tag overrides the GUPR_BackColor tag.
  1569.  
  1570.               GUPR_Current (ULONG)
  1571.                  The initial current value of the progress requester. The
  1572.                  gadget's current value may be changed later by directly
  1573.                  modifying the pg_Current field of the ProgressGad structure.
  1574.                  Use GU_UpdateProgress to redraw the progress requester with
  1575.                  the new value. The pg_Current field must not be larger than
  1576.                  4.294.967.295 / the width of the progress gadget. A "normal"
  1577.                  width of 410 pixels allows a current value of 10.737.418.
  1578.          Defaults to 0.
  1579.  
  1580.               GUPR_Total (ULONG)
  1581.                  The initial total value of the progress requester. The
  1582.                  gadget's total value may be changed later by directly
  1583.                  modifying the pg_Total field of the ProgressGad structure.
  1584.                  Use GU_UpdateProgress() to redraw the progress requester with
  1585.                  the new value. The total value can be as large as a longword
  1586.                  allows (4.294.967.295), but you can't display a current value
  1587.                  larger than 4.294.967.295 / the width of the progress gadget.
  1588.          Defaults to 100.
  1589.  
  1590.          LABEL_KIND
  1591.            A text label. Use this to avoid the use of absolute placement
  1592.            of text that you print into the window. Supports the most of
  1593.            the text placement and shadow flags for the BEVELBOX_KIND.
  1594.  
  1595.            The function GU_RefreshBoxes() can be used to redraw all
  1596.            text created by LABEL_KIND gadgets.
  1597.  
  1598.            Extra tags for LABEL_KIND:
  1599.  
  1600.               GULB_TextColor (ULONG)
  1601.                  Selects which color to print the text in. Defaults to the
  1602.                  color of the TEXTPEN.
  1603.  
  1604.               GULB_TextPen (ULONG)
  1605.                  Selects which pen to print the text in. Defaults to TEXTPEN.
  1606.                  This tag overrides the GULB_TextColor tag.
  1607.  
  1608.               GULB_Flags (ULONG)
  1609.                  Flags for text placement, text shadowing and 3D text:
  1610.  
  1611.                  ___1_____2_____3___
  1612.                  |_____|_____|_____| A
  1613.                  |_____|_____|_____| B 
  1614.                  |_____|_____|_____| C
  1615.                  
  1616.                  Y-pos flags
  1617.                  ~~~~~~~~~~~
  1618.                     LB_TEXT_TOP    - Places the topmost point of the text below
  1619.                                      the upper border of the box (row A)
  1620.  
  1621.                     LB_TEXT_MIDDLE - Places the text centered in the box, not
  1622.                                      counting in the part of the text that is
  1623.                                      below the font's baseline (row B)
  1624.  
  1625.                     LB_TEXT_BOTTOM - Places the text at the bottom of the box.
  1626.                                      Any part of the text that is below the
  1627.                                      baseline will be below the box (row C)
  1628.  
  1629.                  X-pos flags
  1630.                  ~~~~~~~~~~~
  1631.                     LB_TEXT_CENTER - Places the text centered on the width of
  1632.                                      the box (column 2).
  1633.  
  1634.                     LB_TEXT_LEFT   - Places the text left adjusted in the box
  1635.                                      (column 1)
  1636.  
  1637.                     LB_TEXT_RIGHT  - Places the text right adjusted in the box
  1638.                                      (column 3)
  1639.  
  1640.                  Combined flags
  1641.                  ~~~~~~~~~~~~~~
  1642.                     LB_TEXT_TOP_CENTER    - LB_TEXT_TOP + LB_TEXT_CENTER
  1643.                     LB_TEXT_TOP_LEFT      - LB_TEXT_TOP + LB_TEXT_LEFT
  1644.                     LB_TEXT_TOP_RIGHT     - LB_TEXT_TOP + LB_TEXT_RIGHT
  1645.  
  1646.                     LB_TEXT_MIDDLE_CENTER - LB_TEXT_MIDDLE + LB_TEXT_CENTER
  1647.                     LB_TEXT_MIDDLE_LEFT   - LB_TEXT_MIDDLE + LB_TEXT_LEFT
  1648.                     LB_TEXT_MIDDLE_RIGHT  - LB_TEXT_MIDDLE + LB_TEXT_RIGHT
  1649.  
  1650.                     LB_TEXT_BOTTOM_CENTER - LB_TEXT_BOTTOM + LB_TEXT_CENTER
  1651.                     LB_TEXT_BOTTOM_LEFT   - LB_TEXT_BOTTOM + LB_TEXT_LEFT
  1652.                     LB_TEXT_BOTTOM_RIGHT  - LB_TEXT_BOTTOM + LB_TEXT_RIGHT
  1653.  
  1654.                  Default is LB_TEXT_TOP|LB_TEXT_CENTER. Combine the x and y
  1655.                  position flags by OR:ing them together. Don't combine two X
  1656.                  or two Y flags together.
  1657.                 
  1658.                  Shadow placement flags
  1659.                  ~~~~~~~~~~~~~~~~~~~~~~
  1660.                     LB_SHADOW_DR - Places the bevel box text shadow one pixel
  1661.                                    below and to the right of the text. 
  1662.  
  1663.                     LB_SHADOW_UR - Places the bevel box text shadow one pixel
  1664.                                    above and to the right of the text. 
  1665.  
  1666.                     LB_SHADOW_DL - Places the bevel box text shadow one pixel
  1667.                                    below and to the left of the text. 
  1668.  
  1669.                     LB_SHADOW_UL - Places the bevel box text shadow one pixel
  1670.                                    above and to the left of the text. 
  1671.  
  1672.                     LB_SUNAT_UL  - Another name for LB_SHADOW_DR
  1673.                     LB_SUNAT_DL  - Another name for LB_SHADOW_UR
  1674.                     LB_SUNAT_UR  - Another name for LB_SHADOW_DL
  1675.                     LB_SUNAT_DR  - Another name for LB_SHADOW_UL
  1676.  
  1677.                  Default is LB_SHADOW_DR (LB_SUNAT_UL).
  1678.  
  1679.                     LB_3DTEXT    - This flag can be used in place of the tag
  1680.                                    GULB_3DText, TRUE
  1681.  
  1682.               GULB_3DText (BOOL)
  1683.                  Enables the shadow on the text. This tag must be used if
  1684.                  GULB_ShadowColor or GULB_ShadowPen isn't used. Another
  1685.                  way to enable 3D text is to set the flag LB_3DTEXT in the
  1686.                  GULB_Flags tag.
  1687.  
  1688.               GULB_ShadowColor (ULONG)
  1689.                  Selects which color to print the shadow text in. Defaults to
  1690.                  the color of the SHADOWPEN.
  1691.  
  1692.               GULB_ShadowPen (ULONG)
  1693.                  Selects which pen to print the shadow text in. Defaults to
  1694.                  SHADOWPEN. This tag overrides the GULB_ShadowColor tag.
  1695.  
  1696.          Changed tags, and additions to GadTools:
  1697.  
  1698.          LISTVIEW_KIND
  1699.  
  1700.            GTLV_ShowSelected (UWORD id)
  1701.  
  1702.               This tag was changed, so that you don't have to create the
  1703.               string gadget before all other gadgets. The difference from
  1704.               this tag in GadTools, is that we now have to give the ID of
  1705.               the string gadget to use to show the selected item.
  1706.  
  1707.               An example of a valid (and probably most useful) gadget to
  1708.               use for GTLV_ShowSelected:
  1709.  
  1710.               ShowSelGad:
  1711.                   dc.l    GU_GadgetKind,  STRING_KIND,    GU_AutoHeight,  4
  1712.                   dc.l    GU_DupeWidth,   GAD_LISTVIEW,   GU_GadgetText,  NULL
  1713.                   dc.l    TAG_DONE
  1714.  
  1715.               This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
  1716.               array.
  1717.  
  1718.               Special:
  1719.  
  1720.               ti_Data = -1    Creates a read-only gadget below the listview,
  1721.                               same as for GTLV_ShowSelected, 0  for GadTools.
  1722.  
  1723.               ti_Data =  x    Gadget ID for the gadget that the selected item
  1724.                               should be displayed in. Same as GadTools reaction
  1725.                               on a gadget pointer in ti_Data.
  1726.  
  1727.               This gadget's ti_Data field will be changed during the creation
  1728.               of the gadget, but will be changed back before GU_LayoutGadgets
  1729.               returns.
  1730.  
  1731.          MX_KIND
  1732.           The gng_GadgetText field in the NewGadget structure can be used
  1733.           even with MX_KIND gadgets. This should have been included in
  1734.           GadTools. The gadget text will always be placed ABOVE the gadget,
  1735.           on the same side as the other texts for the gadget. Positions are
  1736.           checked against WBPattern & SerialPrefs to get them "right". The
  1737.           GU_GadgetText and GU_LocaleText tags are used to access this field.
  1738.  
  1739.  
  1740.    Tags for all gadget kinds:
  1741.  
  1742.    Gadget width control:
  1743.  
  1744.       GU_Width (UWORD wid)
  1745.          Absolute width of the gadget. Not recommended to use for other
  1746.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  1747.  
  1748.       GU_DupeWidth (UWORD id)
  1749.          Duplicate the width of another gadget.
  1750.  
  1751.       GU_AutoWidth (WORD add)
  1752.          Width = length of text label + ti_Data. For CYCLE_KIND gadgets,
  1753.      the gadget width will be calculated by checking the length of
  1754.      all alternatives and using the one that is widest + 26 as width.
  1755.  
  1756.       GU_Columns (UWORD numcols)
  1757.          Set the gadget width so that approximately ti_Data columns of
  1758.          text will fit.
  1759.  
  1760.       GU_AddWidth (WORD add)
  1761.          Add ti_Data to the total width calculation.
  1762.  
  1763.       GU_MinWidth (UWORD wid)
  1764.          Make the gadget at least ti_Data pixels wide.
  1765.  
  1766.       GU_MaxWidth (UWORD wid)
  1767.          Make the gadget at most ti_Data pixels wide.
  1768.  
  1769.       GU_AddWidChar (WORD chars)
  1770.          Add the length of ti_Data characters to the total width calculation.
  1771.  
  1772.       GU_FractWidth (LONG parts)
  1773.      Divide or multiply the gadget's width with ti_Data. A positive
  1774.      value divides the gadget's width by the ti_Data, a negative ti_Data
  1775.      multiplies the gadget's width with ti_Data.
  1776.  
  1777.     Gadget height control:
  1778.  
  1779.       GU_Height (UWORD hei)
  1780.          Absolute height of the gadget. Not recommended to use for other
  1781.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  1782.         
  1783.       GU_DupeHeight (UWORD id)
  1784.          Duplicate the height of another gadget.
  1785.  
  1786.       GU_AutoHeight (WORD add)
  1787.          Height = height of the gadget's font + ti_Data. This tag doesn't
  1788.          work as it should with MX_KIND gadgets. Will be fixed later.
  1789.          Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
  1790.  
  1791.       GU_HeightFactor (UWORD numlines)
  1792.          Set the gadget height to approximately ti_Data lines.
  1793.  
  1794.       GU_AddHeight (WORD add)
  1795.          Add ti_Data to the total height calculation.
  1796.  
  1797.       GU_MinHeight (UWORD wid)
  1798.          Make the gadget at least ti_Data pixels high.
  1799.  
  1800.       GU_MaxHeight (UWORD wid)
  1801.          Make the gadget at most ti_Data pixels high.
  1802.  
  1803.       GU_AddHeiLines (WORD numlines)
  1804.          Add the height of ti_Data/2 lines to the final height calculation.
  1805.          The numlines argument is given in units of 1/2 lines to get
  1806.          better resolution (ti_Data of 4 means that the height of 2
  1807.          lines should be added).
  1808.  
  1809.       GU_FractHeight (LONG parts)
  1810.      Divide or multiply the gadget's height with ti_Data. A positive
  1811.      value divides the gadget's height by the ti_Data, a negative ti_Data
  1812.      multiplies the gadget's height with ti_Data.
  1813.  
  1814.    Gadget top edge control:
  1815.  
  1816.       GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
  1817.       allows any bottom edge control tag to adjust the height, so that both
  1818.       top and bottom edges will be correct.
  1819.  
  1820.       GU_Top (UWORD ypos)
  1821.          Absolute top edge of the gadget. Not recommended to use for other
  1822.          gadgets than the top-most gadgets.
  1823.  
  1824.       GU_TopRel (UWORD id)
  1825.          Make the top edge relative to another gadgets bottom edge. This
  1826.          gadget will be placed BELOW the given gadget.
  1827.  
  1828.       GU_AddTop (WORD add)
  1829.          Add ti_Data to the final top edge calculation.
  1830.  
  1831.       GU_AlignTop (UWORD id)
  1832.          Align the top edge of the gadget with another gadgets top edge.
  1833.  
  1834.       GU_AdjustTop (WORD add)
  1835.          Add the height of the text font + ti_Data to the top edge.
  1836.  
  1837.       GU_AddTopLines (WORD numlines)
  1838.          Add the height of ti_Data/2 lines to the final top edge. The
  1839.          numlines argument is given in units of 1/2 lines to get better
  1840.          resolution (ti_Data of 4 means that the height of 2 lines
  1841.          should be added).
  1842.  
  1843.    Gadget bottom edge control:
  1844.  
  1845.       GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
  1846.       gadget, and allows any top edge control tag to adjust the height, so that
  1847.       both top and bottom edges will be correct.
  1848.  
  1849.       GU_Bottom (UWORD ypos)
  1850.          Absolute bottom edge of the gadget. Not recommended to use for other
  1851.          gadgets than the bottom-most gadgets. Should not be necessary to use
  1852.          at all.
  1853.  
  1854.       GU_BottomRel (UWORD id)
  1855.          Make the bottom edge relative to another gadgets top edge. This
  1856.          gadget will be placed ABOVE the given gadget.
  1857.  
  1858.       GU_AddBottom (WORD add)
  1859.          Add ti_Data to the final bottom edge calculation.
  1860.  
  1861.       GU_AlignBottom (UWORD id)
  1862.          Align the bottom edge of the gadget with another gadgets bottom edge.
  1863.  
  1864.       GU_AdjustBottom (WORD add)
  1865.          Subtract the height of the gadget's font + ti_Data from the top edge.
  1866.          This will move the gadget UPWARDS (ti_Data + font height) pixels.
  1867.  
  1868.    Gadget left edge control:
  1869.  
  1870.       GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
  1871.       and allows any right edge control tag to adjust the width, so that both
  1872.       left and right edges will be correct.
  1873.  
  1874.       GU_Left (UWORD xpos)
  1875.          Absoulute left edge of the gadget. Not recommended to use for other
  1876.          gadgets than the left-most gadgets.
  1877.  
  1878.       GU_LeftRel (UWORD id)
  1879.          Make the left edge relative to another gadgets right edge. This
  1880.          gadget will be placed TO THE RIGHT of the given gadget.
  1881.  
  1882.       GU_AddLeft (WORD add)
  1883.          Add ti_Data to the final left edge calculation.
  1884.  
  1885.       GU_AlignLeft (UWORD id)
  1886.          Align the left edge of the gadget with another gadgets left edge.
  1887.  
  1888.       GU_AdjustLeft (WORD add)
  1889.          Add the width of the gadget label + ti_Data to the left edge.
  1890.  
  1891.       GU_AddLeftChar (WORD chars)
  1892.          Add the length of ti_Data characters to the left edge.
  1893.  
  1894.    Gadget right edge control:
  1895.  
  1896.       GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
  1897.       gadget, and allows any left edge control tag to adjust the width, so
  1898.       that both left and right edges will be correct.
  1899.  
  1900.       GU_Right (UWORD xpos)
  1901.          Absoulute right edge of the gadget. Not recommended to use for other
  1902.          gadgets than the right-most gadgets. Should not be necessary to use
  1903.          at all.
  1904.  
  1905.       GU_RightRel (UWORD id)
  1906.          Make the right edge relative to another gadgets left edge. This
  1907.          gadget will be placed TO THE LEFT of the given gadget.
  1908.  
  1909.       GU_AddRight (WORD add)
  1910.          Add ti_Data to the final right edge calculation.
  1911.  
  1912.       GU_AlignRight (UWORD id)
  1913.          Align the right edge of the gadget with another gadgets right edge.
  1914.  
  1915.       GU_AdjustRight (WORD add)
  1916.          Add the width of the gadget label + ti_Data to the left edge.
  1917.  
  1918.     Other tags:
  1919.  
  1920.       GU_ToggleSelect (BOOL)
  1921.          Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
  1922.          gadgets.
  1923.  
  1924.       GU_Selected (BOOL)
  1925.          Set the initial value of a toggle select gadget.
  1926.  
  1927.       GU_Hotkey (CHAR)
  1928.          Hotkey that should simulate a press (release) of a gadget.
  1929.  
  1930.       GU_HotkeyCase (BOOL)
  1931.          Make the hotkey case-sensitive. Default is not case sensitive.
  1932.  
  1933.       GU_LabelHotkey (BOOL)
  1934.          Get the hotkey directly from the gadget's label. The hotkey can
  1935.          be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
  1936.  
  1937.       GU_RawKey (BYTE)
  1938.          Use a rawkey as a gadget hotkey. May not be case-sensitive.
  1939.         
  1940.    Tags that gives access to other fields in the NewGadget structure:
  1941.  
  1942.       GU_GadgetText (UBYTE *)
  1943.          A pointer to the gadget's label. Will be copied directly into the
  1944.          gng_GadgetText field of the NewGadget structure.
  1945.  
  1946.       GU_TextAttr (struct TextAttr *)
  1947.          A pointer to an initialized TextAttr structure (to select the font).
  1948.          Will be copied directly into the gng_TextAttr field of the NewGadget
  1949.          structure.
  1950.  
  1951.       GU_Flags (ULONG)
  1952.          Gadget flags. Currently available flags are as for GadTools, but
  1953.          here is a short list of them:
  1954.  
  1955.          PLACETEXT_LEFT - Place the gadget label right aligned on the left
  1956.                           side of the gadget.
  1957.  
  1958.          PLACETEXT_RIGHT - Place the gadget label left aligned on the right
  1959.                            side of the gadget.
  1960.  
  1961.          PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
  1962.  
  1963.          PLACETEXT_BELOW - Place the gadget label centered below the gadget.
  1964.  
  1965.          PLACETEXT_IN - Place the gadget label centered inside the gadget.
  1966.  
  1967.          NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
  1968.  
  1969.       GU_UserData (APTR)
  1970.          Storage for your own data. Will probably be removed, since GadUtil
  1971.          uses this filed for an internal structure (with some external
  1972.          available fields).
  1973.  
  1974.       GU_LocaleText (ULONG stringid)
  1975.          Get gadget label from a catalog. This allows easy localization of
  1976.          all new programs.
  1977.  
  1978.  
  1979.    RESULT
  1980.     gad_info - a pointer to a private structure. You must keep this
  1981.            value and pass it to GU_FreeLayoutGadgets() later on
  1982.            in order to free up all resources used by your gadgets.
  1983.            This pointer is also used in a lot of other functions
  1984.            in this library.
  1985.  
  1986.    NOTES
  1987.     You must be careful with the taglist in the lg_LayoutTags field.
  1988.     Tags are processed sequentally in the order you give them in, and
  1989.     if a tag references another gadget (eg. the GL_TopRel tag), then
  1990.     processing of the current gadget halts while the referenced gadget
  1991.     is processed (if it has not already been processed). Problems can
  1992.     occur if this gadget refers back to the original gadget that
  1993.     referenced if, if it is referring to a field that has not yet been
  1994.     processed in that gadget.
  1995.  
  1996.         Also note that you do not have to specify any tags that do not
  1997.         change from gadget to gadget. Just be sure that you know in which
  1998.     order the gadgets are processed (eg. relatives etc).
  1999.  
  2000.     Another thing to note, is that we have tried to make the processing
  2001.     of position and width / height tags as usable as possible, what I
  2002.     mean with this, is that if you eg first define the left edge and
  2003.     then define the right edge, the width will change. BUT, there are
  2004.     special cases when this isn't true. This is because we have tried
  2005.     out this and decided that this was the best way to do it.
  2006.  
  2007.     Here comes some examples of the special cases;
  2008.  
  2009.     dc.l    GU_AlignLeft, GAD_1    ; Left edge aligned with GAD_1's left.
  2010.     dc.l    GU_AlignRight, GAD_2    ; This stretches the gadget, so that
  2011.                     ; both the left and right edges are
  2012.                     ; positioned as defined.
  2013.     ; Then, if we want to move the right edge 2 pixels right, and the left
  2014.     ; edge two pixels right, we might try this:
  2015.  
  2016.     dc.l    GU_AddLeft, -2        ; This works as we want, it moves the
  2017.                     ; left edge to the right place, but it
  2018.                     ; also moves the whole gadget two
  2019.                     ; pixels left..
  2020.  
  2021.     dc.l    GU_AddRight, 2        ; <- This is a common mistake. This
  2022.                     ; moves the whole gadget to the right.
  2023.                     ; Ie. it is moved back to the old
  2024.                     ; position, not as we wanted...
  2025.  
  2026.     ; But if we replace the previous line with the following;
  2027.  
  2028.     dc.l    GU_AddWith,4        ; This works just as we wanted it to.
  2029.                     ; Now the gadget should be 4 pixels
  2030.                     ; wider, two to the left and two to
  2031.                     ; the right.
  2032.  
  2033.     The same goes for GU_AddHeight and GU_AddBottom etc.
  2034.  
  2035.     This is actually a feature. Sometimes you might want to move the whole
  2036.     button, so we made it work this way.
  2037.  
  2038.  
  2039.    SEE ALSO
  2040.     GU_FreeLayoutGadgets(), GU_CreateGadgetA(), gadtools/CreateGadgetA()
  2041.     GU_RefreshWindow(), GU_RefreshBoxes(), GU_UpdateProgress()
  2042. gadutil.library/GU_LayoutMenuItemsA       gadutil.library/GU_LayoutMenuItemsA
  2043.  
  2044.    NAME
  2045.     GU_LayoutMenuItemsA -- Position all the menu items.
  2046.  
  2047.    SYNOPSIS
  2048.     success = GU_LayoutMenuItemsA(menuitem, vi, tags)
  2049.     D0                            A0        A1  A2
  2050.  
  2051.     BOOL GU_LayoutMenuItemsA(struct MenuItem *, APTR, struct TagItem *);
  2052.  
  2053.    FUNCTION
  2054.     Lays out all the menu items and sub-items according to
  2055.     the supplied visual information and tag parameters. You would use this
  2056.     if you used CreateMenusA() to make a single menu-pane (with sub-items,
  2057.     if any), instead of a whole menu strip.
  2058.     This routine attempts to columnize and/or shift the MenuItems in
  2059.     the event that a menu would be too tall or too wide.
  2060.  
  2061.    INPUTS
  2062.     menuitem - Pointer to the first MenuItem in a linked list of items.
  2063.     vi       - Pointer returned by GU_GetVisualInfoA().
  2064.     tags     - Pointer to an array of tags providing optional extra
  2065.                information.
  2066.  
  2067.    TAGS
  2068.     See gadtools/LayoutMenuItemsA() for tags.
  2069.  
  2070.    RESULT
  2071.     success  - TRUE if successfull, FALSE otherwise.
  2072.  
  2073.    SEE ALSO
  2074.     GU_CreateMenusA(), GU_GetVisualInfoA(), gadtools/LayoutMenuItemsA()
  2075. gadutil.library/GU_LayoutMenusA       gadutil.library/GU_LayoutMenusA
  2076.  
  2077.    NAME
  2078.     GU_LayoutMenusA -- Position all the menus and menu items.
  2079.  
  2080.    SYNOPSIS
  2081.     success = GU_LayoutMenusA(menu, vi, taglist)
  2082.     D0                        A0    A1  A2
  2083.  
  2084.     BOOL GU_LayoutMenusA(struct Menu *, APTR, struct TagItem *);
  2085.  
  2086.    FUNCTION
  2087.     Lays out all the menus, menu items and sub-items in the supplied
  2088.     menu according to the supplied visual information and tag parameters.
  2089.     This routine attempts to columnize and/or shift the MenuItems in
  2090.     the event that a menu would be too tall or too wide.
  2091.  
  2092.     These GadTools routines are only here to make it simpler for someone
  2093.     who wants to use them. This for example, is of no use if you use the
  2094.     GadUtil function GU_CreateLocMenuA() to define localized (optional)
  2095.     menus with automatic hotkey handlimg etc.
  2096.  
  2097.    INPUTS
  2098.     menu    - Pointer to menu obtained from GU_CreateMenusA() or
  2099.               GU_CreateLocMenuA().
  2100.     vi      - Pointer returned by GU_GetVisualInfoA.
  2101.     taglist - Pointer to an array of tags providing optional extra
  2102.               parameters.
  2103.  
  2104.    TAGS
  2105.     See gadtools/LayoutMenusA() for tags.
  2106.  
  2107.    RESULT
  2108.     success - TRUE if successfull, FALSE otherwise.
  2109.  
  2110.    NOTES
  2111.     See gadtools/LayoutMenusA() for more information.
  2112.  
  2113.    SEE ALSO
  2114.     GU_CreateMenusA(), GU_GetVisualInfoA(), gadtools/LayoutMenusA()
  2115. gadutil.library/GU_NewList                         gadutil.library/GU_NewList
  2116.  
  2117.    NAME
  2118.     GU_NewList -- Initialize a list header for use.
  2119.  
  2120.    SYNOPSIS
  2121.     GU_NewList(list)
  2122.                A0
  2123.  
  2124.     VOID GU_NewList(struct List *);
  2125.  
  2126.    FUNCTION
  2127.     This initializes a list header for use. Much easier than to do it
  2128.     by hand.
  2129.  
  2130.    INPUTS
  2131.     list - Struct List.
  2132.  
  2133.    RESULT
  2134.     none
  2135.  
  2136.    BUGS
  2137.     none known
  2138.  
  2139.    SEE ALSO
  2140.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  2141.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  2142. gadutil.library/GU_NodeDown                       gadutil.library/GU_NodeDown
  2143.  
  2144.    NAME
  2145.     GU_NodeDown -- Move a node one step towards the end of the list
  2146.  
  2147.    SYNOPSIS
  2148.     success = GU_NodeDown(node, list)
  2149.     D0,SR(Z)              A0    A1
  2150.  
  2151.     BOOL GU_NodeDown(struct Node *, struct List *);
  2152.  
  2153.    FUNCTION
  2154.     Move a node one step downwards in a list. To do the opposite, see
  2155.     GU_NodeUp().
  2156.  
  2157.    INPUTS
  2158.     node - The node to move.
  2159.     list - The list that the node is a part of.
  2160.  
  2161.    RESULT
  2162.     success - TRUE if the node could be moved, else FALSE.
  2163.     SR (Z)  - 0 if node could be moved, else 1.
  2164.  
  2165.    BUGS
  2166.     none known
  2167.  
  2168.    SEE ALSO
  2169.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  2170.     GU_FindNode(), GU_NodeUp(), GU_CountNodes(), GU_NewList(), GU_SortList()
  2171. gadutil.library/GU_NodeUp                           gadutil.library/GU_NodeUp
  2172.  
  2173.    NAME
  2174.     GU_NodeUp -- Move a node one step towards the top of the list
  2175.  
  2176.    SYNOPSIS
  2177.     success = GU_NodeUp(node, list)
  2178.     D0,SR(Z)            A0    A1
  2179.  
  2180.     BOOL GU_NodeUp(struct Node *, struct List *);
  2181.  
  2182.    FUNCTION
  2183.     Move a node one step up. You can also use the function GU_NodeDown()
  2184.     for moving downwards.
  2185.  
  2186.    INPUTS
  2187.     node - The node to move.
  2188.     list - The list that the node is a part of.
  2189.  
  2190.    RESULT
  2191.     success - TRUE if the node could be moved, else FALSE
  2192.     SR(Z)   - 0 if the node could be moved, else 1.
  2193.  
  2194.    BUGS
  2195.     none known
  2196.  
  2197.    SEE ALSO
  2198.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList(),
  2199.     GU_FindNode(), GU_NodeDown(), GU_CountNodes(), GU_NewList(), GU_SortList()
  2200. gadutil.library/GU_OpenCatalog                 gadutil.library/GU_OpenCatalog
  2201.  
  2202.    NAME
  2203.     GU_OpenCatalog -- Open a message catalog.
  2204.  
  2205.    SYNOPSIS
  2206.     catalog = GU_OpenCatalog(name, version)
  2207.     D0                       A0    D0
  2208.  
  2209.     struct Catalog *GU_OpenCatalog(STRPTR, ULONG);
  2210.  
  2211.    FUNCTION
  2212.     This function opens a message catalog. Catalogs contain all the
  2213.     text strings that an application uses. These strings can easily
  2214.     be replaced by strings in a different language, which causes the
  2215.     application to magically start operation in that new language.
  2216.  
  2217.     Catalogs originally come from disk files. This function searches
  2218.     for them in the following places:
  2219.  
  2220.         PROGDIR:Catalogs/languageName/name
  2221.         LOCALE:Catalogs/languageName/name
  2222.  
  2223.     where languageName is the name of the language associated with the
  2224.     locale parameter.
  2225.  
  2226.    INPUTS
  2227.     catalogname - the NULL terminated name of the catalog to open (just
  2228.               the name, not the complete path to it).
  2229.  
  2230.     version - required version of the catalog to open. Passign 0 as version
  2231.           number means that the program will accept any found version of
  2232.           the catalog. Other values than 0 means exactly that version.
  2233.  
  2234.    RESULT
  2235.     catalog - A message catalog to use with GU_GetLocaleStr or any of the
  2236.           Locale library functions or NULL. NULL is returned on error
  2237.           or if the application can use its built-in strings instead
  2238.           of loading a catalog from disk.
  2239.  
  2240.    EXAMPLE
  2241.     GU_OpenCatalog("myprogram.catalog",0);
  2242.  
  2243.     will open any version of the catalog file "myprogram.catalog" found
  2244.     in either PROGDIR:Catalogs/languageName/ (where the program was started
  2245.     from), or LOCALE:Catalogs/languageName/.
  2246.  
  2247.     GU_OpenCatalog("myprogram.catalog",5);
  2248.  
  2249.     will open version 5 of the catalog file. If v5 is not available, the
  2250.     program will use its internal strings.
  2251.  
  2252.    NOTES
  2253.     If you want to specify other tags than the version tag, you must
  2254.     use the Locale library OpenCatalog(). This function is generally a
  2255.     shortcut to that function. By using this routine, you may not need
  2256.     to open Locale library at all.
  2257.  
  2258.     This routine assumes that the built-in language of the program is
  2259.     english. If you write your programs in another language, you must
  2260.     open the catalog by yourself.
  2261.  
  2262.    SEE ALSO
  2263.     GU_CloseCatalog(), locale/OpenCatalog()
  2264. gadutil.library/GU_OpenFont                       gadutil.library/GU_OpenFont
  2265.  
  2266.    NAME
  2267.     GU_OpenFont -- Load and get a pointer to a disk or system font.
  2268.  
  2269.    SYNOPSIS
  2270.     font = GU_OpenFont(textAttr)
  2271.     D0                 A0
  2272.  
  2273.     struct TextFont *GU_OpenFont(struct TextAttr *);
  2274.  
  2275.    FUNCTION
  2276.     Open a disk or ROM based font. Uses diskfont library if available.
  2277.     Much easier to use than the standard OpenFont functions.
  2278.  
  2279.    INPUTS
  2280.     textAttr - This is a pointer to a TextAttr structure.
  2281.  
  2282.    RESULT
  2283.     font - Struct TextFont ot NULL for failure.
  2284.  
  2285.    BUGS
  2286.     none known
  2287.  
  2288.    SEE ALSO
  2289.     GU_CloseFont()
  2290. gadutil.library/GU_PostFilterIMsg           gadutil.library/GU_PostFilterIMsg
  2291.  
  2292.    NAME
  2293.     GU_PostFilterIMsg -- Return the unfiltered message after
  2294.                  GU_FilterIMsg() was called, and clean up.
  2295.  
  2296.    SYNOPSIS
  2297.     imsg = GU_PostFilterIMsg(modimsg)
  2298.     D0                       A1
  2299.  
  2300.     struct IntuiMessage *GU_PostFilterIMsg(struct IntuiMessage *);
  2301.  
  2302.    FUNCTION
  2303.     NOTE WELL:  Extremely few programs will actually need this function.
  2304.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  2305.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  2306.  
  2307.     Performs any clean-up necessitated by a previous call to
  2308.     GT_FilterIMsg().  The original IntuiMessage is now yours to handle.
  2309.     Do not interpret the fields of the original IntuiMessage, but
  2310.     rather use only the one you got from GT_FilterIMsg().  You
  2311.     may only do message related things at this point, such as queueing
  2312.     it up or replying it.  Since you got the message with
  2313.     exec.library/GetMsg(), your responsibilities do include replying
  2314.     it with exec.library/ReplyMsg(). This function may be safely
  2315.     called with a NULL parameter.
  2316.  
  2317.    INPUTS
  2318.     modimsg - A modified IntuiMessage obtained with GU_FilterIMsg(),
  2319.               or NULL.
  2320.  
  2321.    RESULT
  2322.     imsg - a pointer to the original IntuiMessage, if GT_FilterIMsg()
  2323.            returned non-NULL.
  2324.  
  2325.    NOTES
  2326.     See gadtools/GT_PostFilterIMsg for more information.
  2327.  
  2328.    SEE ALSO
  2329.     GU_FilterIMsg(), gadtools/GT_PostFilterIMsg()
  2330. gadutil.library/GU_RefreshBoxes               gadutil.library/GU_RefreshBoxes
  2331.  
  2332.    NAME
  2333.     GU_RefreshBoxes -- Redraw all bevel boxes in a window.
  2334.  
  2335.    SYNOPSIS
  2336.     GU_RefreshBoxes(window, gad_info)
  2337.                     A0      A1
  2338.  
  2339.     VOID GU_RefreshBoxes(struct Window *, APTR);
  2340.  
  2341.    FUNCTION
  2342.     Redraw all bevel boxes and PROGRESS_KIND gadgets in a window.
  2343.     Also refreshes all text in the window that is created by the
  2344.     LABEL_KIND gadget. This function is basically the same as
  2345.     GU_RefreshWindow, without a call to the GT_RefreshWindow
  2346.     function.
  2347.  
  2348.    INPUTS
  2349.     window - Window to be refreshed.
  2350.  
  2351.     gad_info - The value returned by GU_LayoutGadgetsA()
  2352.  
  2353.    RESULT
  2354.     none
  2355.  
  2356.    BUGS
  2357.     no known
  2358.  
  2359.    SEE ALSO
  2360.     GU_UpdateProgress(), GU_RefreshWindow()
  2361. gadutil.library/GU_RefreshWindow             gadutil.library/GU_RefreshWindow
  2362.  
  2363.    NAME
  2364.     GU_RefreshWindow -- Redraw bevel boxes and gadgets in a window.
  2365.  
  2366.    SYNOPSIS
  2367.     GU_RefreshWindow(window, gad_info)
  2368.                      A0      A1
  2369.  
  2370.     VOID GU_RefreshWindow(struct Window *, APTR);
  2371.  
  2372.    FUNCTION
  2373.     Perform the initial refresh of all the GadTools gadgets you have
  2374.     created. After you have opened your window, you must call this
  2375.     function. Or, if you have opened your window without gadgets,
  2376.     you add the gadgets with intuition/AddGList(), refresh them using
  2377.     intuition/RefreshGList(), then call this function. You should not
  2378.     need this function at other times.
  2379.  
  2380.     This function differs from the gadtools/GT_RefreshWindow(), in that
  2381.     is also renders all bevelbox kind gadgets. If NULL is given in
  2382.     gad_info, no boxes will be rendered, and this function will work
  2383.     exactly as the GT_RefreshWindow().
  2384.  
  2385.    INPUTS
  2386.     window - pointer to the window containing GadTools gadgets.
  2387.  
  2388.     gad_info - the value returned from GU_LayoutGadgetsA(), or NULL.
  2389.  
  2390.    SEE ALSO
  2391.     GU_RefreshBoxes(), GU_UpdateProgress()
  2392. gadutil.library/GU_ReplyIMsg                     gadutil.library/GU_ReplyIMsg
  2393.  
  2394.    NAME
  2395.     GU_ReplyIMsg -- Reply a message obtained with GU_GetIMsg().
  2396.  
  2397.    SYNOPSIS
  2398.     GU_ReplyIMsg(imsg)
  2399.                  A1
  2400.  
  2401.     VOID GU_ReplyIMsg(struct IntuiMessage *);
  2402.  
  2403.    FUNCTION
  2404.     Return a modified IntuiMessage obtained with GU_GetIMsg(). If you
  2405.     use GU_GetIMsg(), use this function where you would normally have
  2406.     used exec/ReplyIMsg() or gadtools/GT_ReplyIMsg(). You may safely
  2407.     call this function with a NULL pointer (nothing will be done).
  2408.  
  2409.    INPUTS
  2410.     imsg - a modified IntuiMessage obtained with GT_GetIMsg(), or NULL
  2411.            in which case this function does nothing.
  2412.  
  2413.    NOTES
  2414.     When using GadUtil, you MUST explicitly GU_ReplyIMsg() all messages
  2415.     you receive. You cannot depend on CloseWindow() to handle messages
  2416.     you have not replied.
  2417.  
  2418.     Starting with V39, this function actually expects a pointer to an
  2419.     ExtIntuiMessage structure, but the prototype was not changed for
  2420.     source code compatibility with older software.
  2421.  
  2422.    SEE ALSO
  2423.     GU_GetIMsg()
  2424. gadutil.library/GU_SetGadgetAttrsA         gadutil.library/GU_SetGadgetAttrsA
  2425.  
  2426.    NAME
  2427.     GU_SetGadgetAttrsA -- Change the attributes of a GadTools gadget.
  2428.  
  2429.    SYNOPSIS
  2430.     GU_SetGadgetAttrsA(gad, win, req, taglist)
  2431.                        A0    A1  A2   A3
  2432.  
  2433.     VOID GU_SetGadgetAttrsA(struct Gadget *, struct Window *,
  2434.                 struct Requester *, struct TagItem *);
  2435.  
  2436.    FUNCTION
  2437.     Change the attributes of the specified gadget, according to the
  2438.     attributes chosen in the tag list. If an attribute is not provided
  2439.     in the tag list, its value remains the unchanged. This function
  2440.     also stores some information for the hotkey part of the library.
  2441.  
  2442.     Use this in place of the gadtools function GT_SetGadgetAttrsA().
  2443.  
  2444.    INPUTS
  2445.     gad - pointer to the gadget in question. This address may be NULL,
  2446.           in which case this function does nothing.
  2447.  
  2448.     win - pointer to the window containing the gadget. Starting with
  2449.           V39 (of the OS), this value may be NULL, in which case the
  2450.           internal attributes of the gadgets are altered but no
  2451.           rendering occurs.
  2452.  
  2453.     req - reserved for future use, should always be NULL.
  2454.  
  2455.     taglist - pointer to an array of tags providing optional extra
  2456.           parameters, or NULL.
  2457.  
  2458.    TAGS
  2459.     See the GadTools function GT_SetGadgetAttrsA() for all tags, since
  2460.     this is an extended version of that routine.
  2461.  
  2462.    NOTES
  2463.     This function may not be called inside of a GU_BeginRefesh() /
  2464.     GU_EndRefresh() session. (as always, restrict yourself to simple
  2465.     rendering functions).
  2466.  
  2467.    SEE ALSO
  2468.     gadtools/GT_SetGadgetAttrsA(), GU_GetGadgetAttrsA()
  2469. gadutil.library/GU_SetGUGadAttrsA           gadutil.library/GU_SetGUGadAttrsA
  2470.  
  2471.    NAME
  2472.     GU_SetGUGadAttrsA -- Change the attributes of a GadUtil gadget.
  2473.  
  2474.    SYNOPSIS
  2475.     GU_SetGUGadAttrsA(gad_info, gad, win, taglist)
  2476.                           A0        A1   A2   A3
  2477.  
  2478.     VOID GU_SetGadAttrsA(APTR, struct Gadget *, struct Window *,
  2479.                 struct TagItem *);
  2480.  
  2481.    FUNCTION
  2482.     Change attributes of a GadUtil gadget.
  2483.  
  2484.    INPUTS
  2485.     gad_info - The value returned by LayoutGadgetsA().
  2486.     gad      - Pointer to the gadget in question.
  2487.     win      - Pointer to the window containing the gadget.
  2488.     taglist  - Pointer to a TagItem list.
  2489.    TAGS
  2490.     See GU_LayoutGadgetsA() for tags.
  2491.  
  2492.    RESULT
  2493.     none
  2494.  
  2495.    SEE ALSO
  2496. gadutil.library/GU_SetToggle                     gadutil.library/GU_SetToggle
  2497.  
  2498.    NAME
  2499.     GU_SetToggle -- Change status of a toggle-select gadget.
  2500.  
  2501.    SYNOPSIS
  2502.     GU_SetToggle(status, gadget, window)
  2503.                  D0,     A0,     A1
  2504.  
  2505.     VOID GU_SetToggle(BOOL, struct Gadget *, struct Window *);
  2506.  
  2507.    FUNCTION
  2508.     This function selects or unselects a toggle gadget, that means a
  2509.     gadget with the tag GU_ToggleSelect set to TRUE.
  2510.  
  2511.     For some more information about the tags, look in <libraries/gadutil.h>
  2512.     or in the autodoc for the GU_LayoutGadgetsA() function.
  2513.  
  2514.    INPUTS
  2515.     status - New status for the gadget. TRUE for selected, FALSE for
  2516.              unselected.
  2517.     gadget - The gadget to change.
  2518.     window - Window that the gadget is located in.
  2519.  
  2520.    RESULT
  2521.     none
  2522.  
  2523.    BUGS
  2524.     none known
  2525.  
  2526.    SEE ALSO
  2527.     GU_LayoutGadgetsA(), <libraries/gatutil.h>, <libraries/gadutil.i>
  2528. gadutil.library/GU_SizeWindow                   gadutil.library/GU_SizeWindow
  2529.  
  2530.    NAME
  2531.     GU_SizeWindow -- Resize a window, and moves it if necessary
  2532.  
  2533.    SYNOPSIS
  2534.     success = GU_SizeWindow(window, deltax, deltay)
  2535.     D0,SR(Z)                A0      D0      D1
  2536.  
  2537.     BOOL GU_SizeWindow(struct Window *, WORD, WORD);
  2538.  
  2539.    FUNCTION
  2540.     This function sends a reuqest to Intuition asking to size the window
  2541.     the specified amounts. The delta arguments describes how much to
  2542.     size the window along the respective axes.
  2543.  
  2544.     This function works like the Intuition function SizeWindow(), and the
  2545.     parameters are also the same. This function also moves the window
  2546.     automatically if it could not be sized at the current position.
  2547.  
  2548.     Remember that this function does not change the window immediately.
  2549.     Just like the Intuition functions SizeWindow(), MoveWindow() and
  2550.     ChangeWindowBox(), you have to wait for a IDCMP_CHANGEWINDOW IDCMP
  2551.     message to arrive.
  2552.  
  2553.     An extra feature of GU_SizeWindow is that it sends back a result,
  2554.     telling you if the window could be resized or not.
  2555.  
  2556.    INPUTS
  2557.     window - pointer to the structure of the window to be sized
  2558.  
  2559.     deltax - signed value describing how much to size the window
  2560.              on the x-axis
  2561.  
  2562.     deltay - signed value describing how much to size the window
  2563.              on the y-axis
  2564.  
  2565.    RESULT
  2566.     success - TRUE if the window could be sized the specified amount
  2567.  
  2568.     SR(Z)   - 0 if function returns TRUE, 1 otherwise
  2569.  
  2570.    BUGS
  2571.     none known
  2572.  
  2573.    SEE ALSO
  2574.     intuition/ChangeWindowBox(), intuition/SizeWindow()
  2575.     intuition/MoveWindow()
  2576. gadutil.library/GU_SortList                       gadutil.library/GU_SortList
  2577.  
  2578.    NAME
  2579.     GU_SortList -- Sorts all nodes in a list.
  2580.  
  2581.    SYNOPSIS
  2582.     GU_SortNode(list,slavelist)
  2583.                 A0   A1
  2584.  
  2585.     VOID GU_SortList(struct List *, struct List *);
  2586.  
  2587.    FUNCTION
  2588.     Sorts all items an a list and optionally in a slave list.
  2589.  
  2590.     The slave list option can be used eg. if you have a ListView
  2591.     gadget that shows a number of filenames and another list
  2592.     with the path-names to the files in the other list.
  2593.  
  2594.     Note that the slavelist pointer must be NULL if not used.
  2595.  
  2596.    INPUTS
  2597.     list      - A pointer to the list to sort
  2598.     slavelist - A pointer to an optional slave list (or NULL).
  2599.  
  2600.    NOTES
  2601.     Written in assembler using Shell-sort, so it is quite fast..
  2602.  
  2603.    SEE ALSO
  2604.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  2605.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_NewList(), GU_CountNodes()
  2606. gadutil.library/GU_TextWidth                     gadutil.library/GU_TextWidth
  2607.  
  2608.    NAME
  2609.     GU_TextWidth -- Calculate the pixel length of a text string.
  2610.  
  2611.    SYNOPSIS
  2612.     textwidth = GU_TextWidth(string, textattr)
  2613.     D0                       A0      A1
  2614.  
  2615.     ULONG GU_TextWidth(STRPTR, struct TextAttr *);
  2616.  
  2617.    FUNCTION
  2618.     Calculate the length of the text, using the specified font. This
  2619.     function will open the required font, if it isn't opened before.
  2620.  
  2621.    INPUTS
  2622.     string - NULL terminated text to calculate width of.
  2623.  
  2624.     textattr - a filled in TextAttr structure.
  2625.  
  2626.    RESULT
  2627.     textwidth - pixel length of the text
  2628. gadutil.library/GU_UpdateProgress           gadutil.library/GU_UpdateProgress
  2629.  
  2630.    NAME
  2631.     GU_UpdateProgress -- Redraw all or specified progress gadget(s).
  2632.  
  2633.    SYNOPSIS
  2634.     GU_UpdateProgress(window, gad_info, gadget)
  2635.                       A0      A1        A2
  2636.  
  2637.     VOID GU_UpdateProgress(struct Window *, APTR, struct ProgressGad *);
  2638.  
  2639.    FUNCTION
  2640.         Redraws all or one specified PROGRESS_KIND gadget in a window.
  2641.  
  2642.    INPUTS
  2643.         window - the window that the progress gadget is in.
  2644.  
  2645.         gad_info - the value returned from GU_LayoutGadgetsA()
  2646.  
  2647.         gadget - NULL, or a pointer to a specified progress gadget to
  2648.                  redraw. If NULL is given, all progress gadgets will be
  2649.                  redrawn. Use this function to redraw the progress gad
  2650.                  after changing the total or current value.
  2651.                  This function is called automatically from GU_Refresh-
  2652.                  Boxes.
  2653.  
  2654.    SEE ALSO
  2655.         GU_RefreshBoxes(), GU_RefreshWindow()
  2656.